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CHAPTER 1: INTRODUCTION AND OVERVIEW 





1,1 Introduction and plan of the book 
The purposes of this book are to teach competent programming and provide a compre- 
hensive reference text on the PET/CBM range of microcomputers. These aims are not 
entirely compatibie: virtually everyone interested in these machines begina with BASIC 
and progresses to machine-code, but, on the other hand, for completeness it is often 
necessary to mix both types of program. Comparative beginners will therefore find 
themselves skipping quite large sections of temporarily difficult text. [ have included 
demonstration routines in BASIC (Chapter 5), 6502 machine-code (Chapter 12), and 
disk, tape, and printer programming (Chapters 7 and 8}. To reduce the chance of 
wis-keying, these routines have been kept as short as possible; in this way it is poss- 
ible to learn by doing, by experimenting at the keyboard to get the feel of the comm- 
ands, without the tedium associated with entering long illustrative programs. 
Commodore's most recent machines, the VIC home computer and the MMF ‘Micro- 
mainframe’ are not dealt with here, partly for reasons of space. VIC has many things 
in common with CBM microcomputers, MMF rather fewer. My rule has been to try to 
cover most of the common configurations of hardware which exist at present and are 
Hkely to exist in the fairly near future. For this reason littie space has been given tc 
modems, hard disks (‘Winchesters') and networks, while tape and diskettes are ex- 
plained in depth. ['ve documented each of the three versions of CBM BASIC issued to 
date, although with a bias to the later versions. This may seem rather wasteful ~ until 
questions of compatibility between ROMs arise. 


1,2 Conventions 


Most CBM machines switch on in upper-case/ graphics mode, and except in few cases. 
mainly 9032 disk commands, BASIC is printed in upper-case characters here, which 
algo distinguishes BASIC keywords from the normal text. BASIC can of course appear 
im lower-case on the VDU, if the mode is changed, a fact which may cause confusion 
to programmers unused to this dual display. Machine-code and BASIC, entered from 
the keyboard in the usual way. use mostly unshifted keys. 

_ CBM BASIC has special screen-editing commands, which appear within quotes as 
reversed characters. (See Chapter 2). For increased readability I have printed these 
in square brackets - [HOME]. [CLEAR], and so on. Chapter 13 has a LIST routine t 
perform this task automatically for BASIC, 

The only other non-standard notation is the use - for machine-code onty! - of 
round brackets as a shorthand for a 2-byte indirect address. For example, { have 
written (2A) ta denote the two-byte number held in locations 2A and 28, taking the 
first byte as low and the second as high, in accordance with 6502 logic. Similarly. 
(FFPE) is a convenient way to refer to the interrupt address. held in FFFE and FFFF. 

Spelling of computer terms is more-or~leas American. Occasionally BASIC terms 
are written in iower-case, when used In a general sense, not specifically BASIC. For 
exampis, ‘printing to screen’ can use PRINT or some machine-code equivalent, and 
‘peeking’ could mean PEEK or a machine-code command like LDA. 


1.3 Sources of Information 


Manuals CBM's product manuals are widely recognized to be unhelpful; this ls one of 
the reasons for the exiatence of thia book. MOS Technology (now a part of the Comrt- 
odore Semiconductor Group) produces reasonable manuals on 65xx nerica hardware Ane 
S§xx programming. 

Magazines, journals in the U.K. the largest-selling email computer journals are Pract: 
feat Computing and Personal Computer World, Those are not particularly CBM-orient: 
ated. Printout wan, but is no langer. exclusively avout the CBM. Compute! deals with, 
6502 machinon (Apple, Atari, PET/CUM) and ja the best magazine for the non -bryzinne ?. 
Micro haa machine-code articles on the 6502 and G8U9, Uyte magnzine and kilobaud 
Microcomputing are two other well-known general microcomputer publications, other 
market nichos ore covered by (for caxnmple) Creative Computing and Dr Dobba' Journ: 
al, Alb but the Cirat thrae of theno magnzinan are American. There ure also periodicals 
abned at the education market, the home computer and games market, the technlest 
hardware market, and what might be called the uninformed businessman's market. 


* 
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There are four weekly 'throwaways' in the U.K. at the time of writing (Computing, 
Computer Weekly, Datalink and Computer Talk} of which Datalink is most interested 

in microcomputing. 

User groups and newsletters Commodore in Canada produces 'The Transactor’, which 
ia yseful and informative. The U.S Commodore Newsletter (called 'Interface'} is less 
good. The U.K. equivalent was called the PET Users Club Newsletter, later abbrev- 
jated to CPUCN, and renamed ‘Commodore Club News’ in mid-1981. Like all peciodicais, 
it is episodic and fragmentary (I have iost count of the number of reviews of word 
processor packages). However, it is responsive to its readers’ requests. 

User groupy are the best source of up-to-date information. IPUC (‘Independent 
PET Users Group’) has many branches in the U.K. and many experienced software and 
hardware people. Other groups inciude SUPA (‘Southern Users of PETs Association’} 
and the Association of London Computer Clubs, a loose organization of groups which 
meet in polytechnics, universities and community centres, and is not specifically CBM. 
Books*and other publications Osborne/ McGraw-Hiil's *PET/CBM Personal Computer 
Guide’ is issued with PETs sold in the U.S. !t is currently in its third edition, edited 
by Jim Strasma. This omits machine-code, which is covered in a number of books, of 
which a few are explicitly PET: 'Hitch-Hikers Guide to the PET‘ for example. Some 
books appear to de available only in the U.S., for example Gregory Yeb's 'PET User 
Manual’, Nick Hampshire has written three (of a projected ten) books for Commodore 
U.K., including ‘Library of PET Subroutines‘ and 'PET Graphics’. ‘The PET Reveaied 
deals mainly with hardware and the BASIC 1 PET; other hardware books are listed st 
the end of Chapter 9. 

Several compendium-type booka exist, for example by [PUG, by CPUCN, and by 
Printout. The 'Channel Data Book’ is an American compilation of PET/CBM products 
and packages. The ‘Computerist's Guide' is an indexed survey of the contents of moat 

‘ of the microcomputer magazines, arranged by topic. Commadore produce a 'Software 
Encyclopedia', essentially an uncritical list of every type of software package. 


1.8 Acknowledgements 


Peter Best, Jim Molloy and Pete Sydenham of A. Gallenkamp Ltd (who supply labor- 
atory equlpment) provided considerable assistance with this book. I am also grateful 
to the software people who provided ideas and programs, and who are acknowledged 
in the text, and also to Jim Butterfietd for permission to print 'Supermon'. Finally, } 
em grateful to my wife's tolerance during the rather long duration of writing. 

{ have gone to some lengths to test and check the information in this book, end 
in fact belleve it to be more reliable than most on this subject. Nevertheless there are 
certain to be errors, and [ apologize for any inconvenlence or puzzlement which may 
be caused. The usual disclaimer applies: I cannot accept responsiblity for failures in 
software or hardware which may be based on suggestions found in this book. 

There are many company namea, trade marks, and business names mentioned in 
the book: CBM ('Commodore Busineys Machines'}, MMF (™Micro-Mulnframe'), PET ('Per- 
sonal Electronic Transactor') and VIC ('Video Interface Chip‘) are all trade marks of 
Commodore Businesa Machines. PET/CBM ts a general way of referring to Commodore's 
microcomputers with both keyboard and screen, and equipped with Microsoft BASIC. 

Charles (’Chuck') Peddie, the designer of the PET/CBM and also, apparently, 
the 6502 chip, deserves a special mention at thle point, although hia path has 
diverged considerably from Commodore's. 


"Thera are many general docks on computers. Chris Evans wrote popular books on the 
eupposed impact of microprocessors, The technicai side of chips wae doalt with (#.g¢.) 
in ‘Scientific American’, Critica of applications inciude Joweph Weixenbsum, a Profese- 
or et @.1.T, Gerry Wainherg ie well-known (e.g. ‘The Paychology of Computer Progrem- 
ing’), taking a conventional, aptiniatic viewpoint, Pailip Kraft on the other hand hes 
examined de-akilting by management, and women's atatua within the industry. {(Sartoriai 
dconographers might ncte that Weinberg 1a alweys depicted bearded and pulloverad, but 
Kraft oeaatiy-suited), Soma Journalists have drawn attention to the rola of cheap leb=- 
our in the Par East if chip aenufacturs, Academic computing‘'s domination by softeare 
theoreticians bas been attacked by only one hardware-based writer that I know of, fvor 
Catt, who celled programmers ‘updated alerka’. (See e.g. ‘Computer Worshig). 
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t.5 PET/CBM hardware and family tree 
APPROXIMATE CHRONOLOGY OF COMMODORE MICROCOMPUTERS 
G5xx chips: Oy Rockwell, MOS Technology 
KIM; single-board 6502-based microcomputer 


2001-8: 8K RAM, built-in cassette, 8" 40-column white 
ecreen, small keyboard. BASIC 1. (ROM -19, 
issued to replace -L1, cures screen edit bug}. 



















2000 series printers. 
2040 disk drives (DOS 1. 
sequential files only}. 
3040 disk drives (DOS t-.2 
Shugart). 


POQt-16, 2001-32: 16K or 32K RAM, 8” 40-column green 
screen, large keyboard, no cassette. BASIC 2 
CUpgrade ROM’) ineluding monitor. Later re- 
named 3008, 3016, 3032 with "BASIC 3'. 





























4008, 4016, 4032; 87 40-column green screen, large key- aang diak drives (DOS 2.1 
poard, similar to previous except for BASIC 4. including relative files). 
8032 42K RAM, 12" 80-column green screen, extra /8050 disk drives (DOS 2.5 
keys, beeper. BASIC 4 (includes CBM disk Micropolis). 
commands). (ROM -23, issued to replace ROM 
-19, cures bug in DS$). 





















4022 printer (SMX~70). 


008, 9016, 4032; Made with 12” 40-column green screen a750 disk drives (DOS 2.7 
only, with extra keys, beeper. Tandon). 
Ic 22 columns, color with external TV, sounds, 
ME 64K extra RAM in 16 switchable blocks from 
$9000-9FFF, 6502/6809, RS232 and high-speed 
RS232, many languages, existing and under 
development at Waterloo Universtity). 


? BASIC 5 with BCD arithmetic? 40-column VIC, 
discontinued 4@-column CBM? Color CBM? 











The table summarises most of the hardware developments of Commodore to date. I have 
omitted some of the printera. See Chapter 2 for more information on the differences 
between BASIC ROMs, which are also mentioned in pnasing throughout much of the 
book. Chapter 6 deals with disk drives, and Chapter 7 with the commands introduced 
in BASIC 4.0. Printers and other hardware are explained in Chapter 8. A significant 
diffarence between 12" and 8" models ta the CRT controller chip: see Chapter 9 on 
this, which also covers the built-in ‘beeper’. 
Internal tayouts The diagram le a rough gulde to the layout of the main chips and 
ports on the printed circult boards of the early PET, tho @" screen 3060 and 4000 
12" screen 4000 and 8000 serles CBMs, 

iscdas yeaa a* 3000 & 4000 12" 4000 & 8000 
IEEE User Tape g 

Port #1 


6602 unc san ial 
feocsnd 


chips 










IEEE User Tape 
Port #82 


6502 & 

1/5 chips 
RAM chips 
ROM chipa 


Ce. 5504 41/0 
chips 


ROM chips 


FOC BAD 
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CHAPTER 2: BASIC AND HOW IT WORKS 





2.1 Keyhosrd, screen and screen-editing The keyboard and screen are described in 
detail in Chapters § and 9 respectively. These devices offer the most direct commun- 
feation with the machine, The keyboard is decaded by a 6520 chip and ROM software; 
the screen memory is orgenised in a straightforward memory-mapped way. in which 
sequential RAM locations correspond to screen positions moving left to right and down. 
Screens in the CBM have 25 rows. 40-column and 80 column screens therefore require 
1000 and 2000 RAM locations respectively. The screen starts at location $4000 in each 
case, exactly half-way in the memory-map. The entire 4K from $8000 - S8FFF is alloc- 
ated to the screen, and the address-lines connected so that the upper part of this 
block duplicates the lower. (So $8000-$83FF and $8400-$87FF are not distinguished from 
each other in 40-column machines, for example, and a poke or peek to $8000 has the 
same effect as a poke or peek to $8400). A few bytes are left over in RAM which do 
not appear on the screen: 24 in 40 column machines, 48 in 80-column, because 1024- 
1006 = 24 and 2048 ~ 2000 = 48. Tables of hexadecimal and decimal values of screen 
locations are printed in Chapter 9. [t is worth memorizing the figure 32768 (=$8000), 
which is the location of the top-left of screen. Try POKE 32768,33 for instance. 

Screen editing is the process by which characters on the screen are altered and 
moved from the keyboard. PET/CBM has a number of special keys for this purpose, 
which are fairly self-explanatory. The main complication is the use of the quote (") 
to hotd screen-cediting characters in storage in BASIC. When this is done, the charac~ 
ter appeurs as a meaningless graphics symbol, and its printed in the usual consecutive 
sequence without having its usual effect, such as clearing the screen. The exception 
to this exception occura with a few keys, like ‘Delete’, which have to work both in 
quotes and out; the resulting editing system has a few anomalies, which make it less 
easy than might be the case to perform editing tasks. However, it is still noticeabiy 
easicr thar some rival systems. Commodore's manuals and some books go into great 
detall on this; it is much more easily explained by demonstration and trial than by the 
written word, Try the examples which follow if you are uncertain about screen editing; 
without covering every possible aspect, they incorporate most features. 

{i} Editing a line without quotes. Switch on the machine, so Commodore's BASIC 
message appears. Press [HOME].* The message may be edited, by (say) moving the 
cursor right severat positions, then inserting spaces. The end of the line moves right; 
eventually, when it is 80 characters long (94 with VIC!) it will not expand more. 

(ii) Using quotes. Type PRINT ° and a series of miscellaneous keys including 
editing characters. The effect of [RVS], [RVSOFF], [HOME], [CURSOR DOWN], ond 
the rest can be explored in this way. On pressing Return, the line is processed and 
printed. With practice it is ensy to produce quite complicated layouts: PRINT “(HOME)* 
[DOWN }*(DOWNJ*" prints three asterisks diagonuily from the top left of the screen, 

(ili) Editing a line with quotes. Type 1 PRINT "HASIC" so the cursor now Is 
positloned after the second quote, and quotes mode js off, Backspace the cursor one 
Position, and type several (INSERT) characters; the aceond quotation mark will move 
right. Now type the [DELET#} key several times. Delete characters, appearing as 
reversed Ts, fill the space, Press Return, the type RUN Keturn, to see the effect of 
these characters. LIST will redispiny the line. 

(lv) Shift-Return and the ESCape key. Return moves the cursor to the next 
line and causes the edited line ty be processed - l.e. incorporated Into ASIC or ex- 
ecuted in direct mode. Shift-Heturn moves the cursor without causing processing. The 
ESCnpe key (!2-Inch sereen machines only} has an analogous effect from within quates, 
turning off tho quotes made and the reverse mode, an the effect ia Identical to thot 
obtained from Shift Retum canbined with cursor moves back to the eriginal tine. 

iv) BASIC editing. LIST displuys a line, or range of lings, from HASIC. Any 
line may be adited in any way: for example, if the IInenumber Is changed anc Return 
Proased, a duplicato tine Ip produced within the program. An Inolated numbur erases 
the corresponding HASIC Ine, tf there Is one. 





*tn moat af this book Tl have conventionally represented the mpecin) chsractors by a 
fame in capitels within square bracketw, (Chapter 13 haa a routtns which Lists pro- 
gtume in this way), Thia is far wore readable than @ single graphics charecter ebich 
ig itm equivetent. 





a: BASIC 





Lower-case 








Upper-case ; 
2.2. Entry and storage of BASIC BASIC can run in either of two modes: direct (or 
immediate or ‘calcwator’ mode) or program {‘stored') mode. If a line begins with a 
number, it is treated as a program line, and stored in memory with other program lines 
until it is run. If a line does not start with a number it is executed immediately oe 
is pressed, The principles on which immediate mode runs are identical to those alike : 
apply to stored programs; in this and the following sections we shal! therefore mainly 
rograms. : ; 

vc’ Techn ae be examined with the LIST command. However, this provides ey 
clue to the way BASIC is organised in RAM, since it involves an elaborate agkigitd 
decoding. (See Chapter 13). We can look at BASIC in situ using either BASIC or the 


-code monitor in these ways: | 
pane 1-0: FOR J=1025 TO 1200. POKE 32768+K, PEEK(J); I=K+1: NEXT is a simple direct 


i f the screen. 
de line which displays several hundred bytes of BASIC at the top o 
eLowee-coks mode = POKE $9488,14 - gives the clearest representation ). The bytes are 
not easily deciphered, although text (in quotes) is clear enough. In the two examples. 
the first has more text (including REMs) than the second. 


“PRINT USING” ROUTINE “wT + | . ‘ 
aaa sosee ins hk it ___" ¢@ UNDERLINE CSHIFT-#> TIDIES TITLEDMSEEM err 
E "machine code ig now loaded into sys 926 and sys 681-H Mload the prow 

aid ba " VANCOLUYER 
1022,128! «o"ERRRIDUM 3.435 07SR"RICK LEONN © WMARPROMNINICO Lt0.8 ana"! NER 
7* MhRheeenc ce 15,6, 1 SOMERS rt 619 EE SS" Le ey" BS aa 
—_) BLos+"_ 98" VLR" ats its” : 
{ii) After entering the monitor (SYS 4 is easiest) we can display bytes in hexa- 
decimal form from $0400 onwards. With the program 10 PRINT“HELLO" in are y 
: GE SF GA_6a wets tink powler (@ here |. 
get this: | @4ee@ 20 99 22 40 <— AGE + Next Nim's link po 
a e409 45 4C 4C 4F 22 GB (GA GG) ~aadar Basic Granenber {id — 
*t @410 AA AA AA AA AA AR AA AA BOs End-af-line 5 996+ End of prageom. 


for "HELLO" are visible in there, but so is much else. 

gs athe cule on ine following page gives a complete breakdown of the storage of 
Hnes of BASIC, excluding the linenumbers and connecting details. All the components 
are stored In ways which exclude ambiguous interpretation. Literals are held within 
quotes, or after REM or DATA, and are not treated like the remaining BASIC. raid 
ers, as in GOTO 1000 or X=99.8. are also held ag ASCII strings. So that the 1000 9: 
GOTO 1600 occupies 4 bytes, Punctuation (commas, colons, semicolons, but nat ae 
stops which are used as decimal points) ia held as single bytes; so are the specia 
BASIC characters of %, $. {(, and ), Variabie names use alphanumeric characters; the 
initial is always alphabetic, to avoid confusion with numerals. Finally, the mayne 
themselves are held in compact form, as single bytes; see the table. These are = ne es 
‘tokens’. Slightly confusingly, single-byte keywords like <,=,* and / aro atso token a 
Into alternative alngle bytes. Tokens aiways exceed (27; the high bit of the byte is - 
and this enables machine-code to immediately recognise a token. This feature is comme: 
™ He BASIC nee 1s a Mnked Ist! or ‘chain’ of individual program lines. a 
Specially modified, BASIC starts nt $0400 with a zoro byte and ia held in ae ate hg 
locations up in memory. Each line starts with a 2-byte link address, which ja ra : 
nolute address puinter to the link address starting the next fine. Thin is followe bets ; 
the IInenumber, also in 2 byten, In ench ecnse the low byte Js first. Each line is cern 
Inated by a zero byte, and in addition 2 more zero bytes mark the end af the pra 4b 
gram, soa [ink addruss of zero denotes the end. As wo shall see, BASIC is aapeor 
ed-by a sect of puinters which monitor important features aa 8 progrum runs, if these 
are maiifiod, varkwun non-standard uffects cun be realized. ee 

The link addresses, Unenumbers, tukens and so on can be idendtifled with prac , 
{ce quito enaily: the one-ilne program above has had {is marked to show how they oe 
arranged. Again, thls is standard Microsoft, as ia the use uf the zero byte to mar , 
the end of 2 Iine. (It (x not unlversal; Apple Integer HASIC vers J to mirk uneda ¢ 
nes, and has an offsct pointer, with maximum 255, to the next ine}, 





ty 


cram ne 
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PET/CBM INTERNAL STORAGE OF BASIC 















































80 END 160 
129 91 FOR 161 

34.22" 66 428 130 @2 NEXT 162 
4523 # G7 aac 131 83 DATA 163 
$6 249 68 44D 132 84 INPUT# 164 
4725 % 69 45 E 133 85 INPUT =:165 
a8 26 2 70 46 F 134 86 DIM 166 
39 27° «71476 135 87 READ 167 
40 28 ( 72 48H * 496 88 LET 168 
4129) 73491 137 B89 GOTO 169 
42 2A * 74 444 138 8A RUN 170 
43 2B + 75 40K 199 88 IF 171 
442C, T64CL 140 8C RESTORE 172 
45 2D- 77 4DM 14k BDGOSUB = 1173 
4EN 142 EZ RETURN t74 

4F 0 143 8F REM 175 

50 P 144 90 STOP 176 

51 Q 145 91 ON 177 

52 R 146 92 WAIT 178 

$35 147 93 LOAD 179 

54 T 148 94 SAVE 140 

55 U 149 95 VERIFY 181 

56 V 150 96 DEF 182 

57 W 151 97 POKE 183 

58 X {52 99 PRINT# 184 

59 Y 153 99 PRINT 185 

5A Z 154 9A CONT 186 

SB { 155 9B LIST 187 

§C \ 156 9C CLR 188 

5D} 167 9D CMD 189 

5E 158 9E SYS 199 

5F ¢ 159 9F OPEN 191 





AQ CLOSE 182 
ALGET 193 
A2NEW 194 
AJTABL 195 
AdTO 196 
ASFEN 197 
AGSPC( 158 
ATTHEN 199 
A8NOT 200 
AQSTEP 201 
AA? 262 
AB= 203 
Ac* 204 
AD? 205 
AE 206 
AFAND = 207 
BO OR 208 
Bi> 209 
B2= 210 
BI 211 
B4SGN 212 
BS INT aad 
BEABS 214 
B7USR 215 
BSFRE 216 
B9POS 217 
BASQR 218 
BBRNO 219 
BCLOG 220 
BDEXP 221 
BECOS 222 
BF SIN 223 


2; BASIC 











cG TAN 
c1 ATN 
C2 PEEK 

C4 LEN 

C4 STR$ 

cS VAL 

cé ASC 

C7 CHRS 

C8 LEFT$ 

co RICHTS 

CA MIDS 

cB GO* 

cc CONCAT* 
CD DOPEN 

CE DCLOSE 
CF RECORD 
DO HEADER 

Dl COLLECT 
D2 SACKUP 
D3 COPY 

D4 APPEND 

D5 DSAVE 

D6 DLOAD 

DI CATALOG 
Ds RENAME 
D9 SCRATCH 
DA DIRECTORY 
DA 

DC ---See 

DD Notea~-- 
DE 
DF 


Notes: (i} Valid BASIC bytes from 0-127. in bold type, are space, “ # $B), and 


. in order, followed by 0-9, : ; and A- Z. The zero byte is vali 


and end-of-program marker, On LIST, bytes from 96-127 appear 


characters 32-63, but, like the italicised chara 

ei) Velid bytes from 128 - 255 are BASIC tokens; 
and the following keywords 
Bytes beyond the end of the table list as apparent dup 


and as error messages and garbage In BASIC 4. Note thet Shlft-K (BASIC t), Shift-L 


BASIC i, while CONCAT 


eters above, cause 


d as an and-of-line 
as duplicates of the 
?SYNTAX ERROR. 


and GO is omitted from 
are omitted from BASIC<4. 
jicates of keywords in BASIC<4, 


(BASIC 2), and Shift-[ (BASIC 4 - may not be on the keyboard!}, all cause LIST to 


stop with ?SYNTAX ERROR. Spurioun keywords ¢ 
(i) The quotation mark, CHR$(34}, can o 


an LIST but will not run. 
{ course legitimately precede any 


character. 


When a BASIC program is entered at iha key 


which Return Is pressed are transferred to a 


verajons mover It to $0200 - $9250, After the Jine has bee 
any that are found ure converted inte tokens. Tha 


keyworda ; 


merged into the program in memory, its position dete 


buffe 


board, the contents of the line in 


r. This in 80 characters long, end 
ean hold one Iine; BASIC t's buffer wos in the zero-page ($0A - SSA), but Inter BASIC 


n meved, Lt {a scanned for 
tokenlied Ling ls then 
rmined by tta linenumber. The 


tokenlsatlon process can be watched (ace Chapter 13) with the ald of a machine-code 
routine which displaym the input buffer at tho top of tha rcreen. 
line is exceuted In the Input buffuc; thin enables a line like PRINT “[CLEAR HELLO" to 
t in erased from the screon as lt runs. 


run from the atart to the end, ever though | 


40-column BASIC has provision in It to distinguish 40- 
Hnea; « acreon-ling table of 25 bytes noida a value for 
two linen haya been conceptually connected by the sarven editor. 
listed in Chapter 5. 


forms of keywords are acceptable, Thuse are 


In direct male, the 


character Ines from §0-character 
each ling to indicate whether 


Note alae ihat shart 
‘They provide a way 
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to enter lines which otherwise might be overlength. Provided that the line doesn't 


exceed 80 characters. this is acceptable, aithough wher LISTed the same line will be 

hard to edit, since it will overtlow the end of the g0-character line. The order of the 
keywords in the table determines whether an abbreviation is possible; if there is any 

ambiguity, the interpreter picks the first in the table. So £ shift-N enters END, and 
F shift-O enters FOR; put R shift-£ is READ, RESTORE needing RE shift-A. INPUT# 
can be entered as I shift-N, but INPUT cannot be abbreviated by this method. PRINT 
Is only available in 8 short form because '7t ig apecially written in to the interpreter. 


2.3 Variables, variable storage, and pointers A ‘variable’ ia an algebraic idea: @ 
symbol stands for # quantity (or string of Characters). Microsoft BASICs have three 
variable types: numeric, integer. and atring. The interpreter distinguishes between 
them by testing for a character after the alphanumeric characters which make up the 
name. '$' and ‘%’ represent string and integer variables respectively. H there is no 
epecial character, the variable is numeric or ‘peal’. The presence of '{' denotes that 
the variable is subscripted. CBM BASIC allows multi-dimensioned arrays; the individ- 
ual arguments are separated by commas. Three array types exist, distinguished by the 


Interconversion between variable types is sutomatic ag far as numerals are con- 
cerned; string-to-numeric conversion and vice versa requires special functions. For 
exampie, L%<L/256 automatically rounds 7256, and checks that the result is in the 
signed, 2-byte range (- 32768 to 32767) to which CBM integers are confined. And 
L$xSTA$(L) and L=VAL(L$) or LyeVAL(L#) convert numerals to strings and vice-versa, 
subject to certain rules (see Chapter 5). Two other interconversion functions are 
cuzg$ andasc, which operate on single bytes and enable expressions which would other 
wise be treated 4s apecial cases to be processed. Q$=CHR$(34) assigns the quote to 
variable Q$; and 10 GET X93: IF Xg="" GOTO 10 / 20 IF ASC(X$) = 13 GOTO 100 / ETC. 
tests for Return, which is only possible with the aid of these byte-level commands. 

Variables’ names are subject to these rules: 

1, The first character must be alphubetic. 

2, The next character may be alphanumeric. 

3. Any further aiphanumerics are valid, but not considered part of the name. 

4. The next character may be $ or $, denoting integer or string respectively. 

$§. The next character may be (, denoting @ aubscripted variable. 

6. A name cannot include reserved words, as the translater will treat them as 
keywords and tokenise them. Note that reserved variabies (Th, ST. DS, DS! 
can be incorporated in names, 48 they are not keywords. : 

All these rules simply have the purpose of removing ambiguity and making storage 
convenient and fast. If (say) 1A were a valid variable name, 100 1A=1 would require 
special syntactical treatment to distinguish it from 1001 A=1. And if other symbols thé 
alphanumerics were permitted, 80 that B= were a valid name for instance, again this 
could cause problems. We shall see very shortly why names of length 2 are used. 

The next page has @ table of names; some are valid, others are not. Italicised 
text Indicates the presence of a keyword, making the name unacceptable. All those 
names without italics are perfectly usable; but care has to be taken to avoid using 
what la in fact one variable under the impression that It is two or more: for example 
NUMBER and NUMERAL are legitimate variables, but both could be replaced by NU, and 
Program which ‘thinks! they are different will give surprising reaults, 

Even with valid names, some ambiguity is possible, particularly if a program i 
‘crunched’ ao that ail epaces are removed (except in quotes}. The next sectlon has 
examples. 

P variables, in elthor direct mode or program mode, sre stored after thea progra 
currently in memory: the space bs known to be there, and ag @ program runs variat 
are created and modifled in this area. Sirings, because of their dynamic nature, do 
fit tidsiy into this scheme, and aro stored in two ports, a name with a pointer, anid 
the string pointed to; with most variabics’ manipulations involving strings. RAM has 
be checked to onaure there is room to store the next atring. Chapter 5, in DIM ane 
PRE and elsewhere, didcussea storage. Hefore looking at the aystem of pointers. let 
examine (he RAM storuge of euch type of variable, These con be peeked in exactly 
mime ways that BASIC programs can be. There ia 4 complicniion that the actual val! 
stored may vary; & BASIC program peeking values whieh follow itnelf may product 
different renuita at difforent thos. Provided we avald minar confuslons of this aort 


can investigate the way In which BASIC variables are stored, 
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EXAMPLES OF LONG NAMES FOR VARIABLES 


COLLAR Limit PENCE TOP 
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AGE ENO LINES PERCENT TOTAL 
AMOUNT ESCAPE LOAD PIA TOWN 
ANSWER ESTIMATE LOCATION PLACE TRACK 


ARRAY EVALUATION LOW POSITION TYPE 
AVAILABLE EXTENT LOWER POUND UNDER 


AVERAGE FILE MACHINE PRICE UNIT 

BAD FINAL MARGIN PRIMARY UPPER 
BEST FINISH MARK PRINT VALUE 
BETTER FIRST MARKUP PRODUCT VARIABLE 
BIT FLASH MASS PROFIT VARIATION 
BLOCK FORM MEAN QUANTITY VARIETY 
BRANCH FORMULA MEASURE RATE VERTICAL 
BYTE FORWARD METER RECORD “VIA 
CALCULATION FOUND METRE REFERENCE WAGE 
CALENDAR FRACTION MINUTE REORDER WEIGHT 
CANCEL FUNCTION MONEY REVERSE wORD 
CATA cooD MONTH RIGHT WORST 
CENTER GUESS NEVER ROOT YEAR 
CENTRE HEX NEW ROUNDING 

CODE HORIZONTAL NOTE SALARY 

COMMAND HOUR NOW SALES 

COMMENT IEEE NUMBER SEARCH 


CONTENTS IN NUMERAL SECOND 
CONTROL INCOME NUMERATOR SECONDARY 
CORRECT INDEX OFF SECTOR 


COST inPUuT OK SKIP 

DATA INTEGER OLD SOLUTION 
DATE INTEREST ON STANDARD 
DAY INVENTORY ORDER START 
DECIMAL INVESTMENT OUT STATEMENT 


OEFAULT INVOICE OUTPUT STOCKS 
DENOMINATOR ITEM OVER STRING 










DERIVATIVE KILO PACK SUBSTITUTE 
DEVIATION LABOR PAGE SUBTOTAL 
DIAMETER LABOUR PARAMETER SUM 
DiFFERENCE LAST PARTS SURPLUS 
DIVIDE LEFT PAUSE TABULATE 
DISCOUNT LENGTH TIME 

TITLE 


Simple variables Every non-array variable occuples 7 bytes of RAM following Its pro- 
gram, or, in direct mode with no stored program, in BASIC's RAM apace starting at 
$0401. fn additlon, atrings occupy the top of RAM. BASIC 4 strings ore stored with a 
2-byte polnter back to their names. Of the 7 bytes, the first two hold the name, The 
high bit of cach may be set or unset, gtving 4 permutations of effectively the same 
name; in this way, the variabies A, At, A$, and FN A are distinguished by the inter- 
preter. At run time, an expression tike A=4 causes the entire table of variaubies to be 
soarched, If A is not present, and A to be set up at the end of the current thie, For 
this reason, BASIC mny be noticeably faster Jf varlubles are defined in order of im- 
portance. Note that all four types of variable aro atored together; there is no separ- 
ation of atelngs from real numbers, for exumply, Note alse that arrays are blorod after 
the almpie variables; their range is defined by an extra pointer. Tala Is necensary 
becauge arrays would slow voriablea' search timen by xpolling the conuinioncy with 
whieh 7 enn bo added to each simple varlable’s pointer to find the next, At any rate, 
this i# standard Microsoft. Consequently, new variables, deflacd after arrays, caouad 
the antiro array structure to ba moyed 7 bytes up HAM, which may ganerate strange 
delays, and Iso further renson to define varicbles at a program's atirt, The storage 
syntem is rather wasteful: 3 bytes are unused with inteyur-type varlables, 2 wlth 
atrings, and 1 with function definitions. 
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Subscripted variables These are segregated from simple variables, and constructed 
differently: each array has an offset pointer to the next array. since obviously all 
arrays are not the same length. Microsoft's aystem saves space compared with simpte 
variables: integer arrays. in particular, are very efficient in space usage. It also 
avoids the possibility of confusion between simple variabies and arrays, which other- 
wise could arise. 


Storage of CBM variables 


Variable type: Name: Detaiis of storage: 
5 ASCII [__waNTIgSA SSCS 
eee a Per | axpoeer | se 
Sign bit 
ASC+128 
ime scan GY come [owe] Te | 


Sign bit 
ASC+t28 [ POINTER _—| 
String [ ascrn | or 128 [mc | ram oo 


F e 1 ASCII POINTER TO DEF'N POINTER TO YARTABLE 
unetion defn [asceize | S05) | “ap pyre [Rt GVie| to BYTE Yr BYTE 


The table shows all four types of simple variable. The name carries an impticit type 
declaration: thus a name consisting of the values 71 and 199 (decimai) is GG$, and a 
Name consisting of 65 and 0 is A. Taking these in turn, note that a floating-point 
number's value is £XP-129 wi m2 ) 


Sey Se “O +iza *izeeose * 
which can be expressed in various ways. (Sec e.g. Chapter 16, and Chapter 5 on 
VARPTR). This is a standard floating-point format. Integers are held in signed, 2byte 
form, with range -32768 to 32767. The vatue may be found from this formula: 

(HL AND 227)9256 + LO + (HI>127) «32768. 

Por example, HI=0 and LO=100 stores an Integer variable of value 100; HI=255 and LO= 
156 stores -100. (The two expressions add to 0 with overflow). 

The string name is held with a pointer ta the start of the string, which contin- 
ues up memory for length LEN. (See LEN in Chapter 5), BASIC 4 differs from earlier 
BASICs in that each string nas a pointer, which points to the string's name lower in 
RAM. This la to facilitate memory freeing; sce Chapter 5 on FRE for thia. 

pra sn s ay 

f pio | HI 
Main pointer Pointer back to LEN of itself in low RAN 

A function definition has two pointers; one to the definition In the body of the 
BASIC program, and one to the floating-point dependent variable. They point just 
after the '=' sign and to the exponent byte respectively. The final byte is garbage, 
®enerated when the definition is act up, and is not used, 

Strings and function definitlons, unlike numeric variables, can be defined sa 
that thelr pointers indicate some point within BASIC. ff a new program Is loaded and 
run, retaining these values (i.e. by LOAD from within a program), the pointers will 
no longer Indicate correct values, #0 a string of this sort will be garbage. and 4 
function In likely to give a SYNTAX ERROR mesnage. Strings can be moved Into high 
RAM using X5=X$+"" and the equivalent for other strings, but functlone must be re- 
defined ag a rule. 


Subscripted vartables (arrays} 
| orrget [No. OF [ LAST DIM+ 1 


ice css Data 
TLow[wiGn | pius | wicd | cowj’'‘{wrcH [cow 


BABIC 4 STRINGS: 


The dlagram nhows the layout of all three array types, The high-bit conventions for 
type are Identical to those for simple viriablea (there in no equivatont to the function 
definition), The ‘offsat' figure is the total Jongth of the low-RAM poet of the arroy; 
we shall noe how thtn In calculated. The ‘number of dimenalona' figure is i for a one 
dimenatonal array, @#.g. A(x}; 2 for a two-dimensional array Ilke Cix.y) and so on. 
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A set of pairs of bytes holds the value of DIM¢1: since dimensions ere counted from 
the zeroth element. Finally, we have the dats. This is held in S-byte batches (reais}, 
}byte batches (strings) and 2-byte batches (integers), It is exactly similar to that 
for simple variabies, except that spare bytes are not wasted. For example, the string 
arrey data consists of sets of 3 bytes, consisting of the length of each string in the 
array and its pointer. Strings are, of course, heid in high RAM or in the body of a 
BASIC program. The variables. or pointers, are held in strict sequence, which is 
ascending order of argument, with the lattermost variables changing ieast frequently. 
For exampie, DIM A(i,2} stores its variables in the order 

A(O,0) A(1,0) A(O,1) ACi,1) A(O,2} A(1.2), and DIM X(1,1,2) in the 
order 

(0.0.0) (1,0,0) €0,1,0) (1,1,0) (0,0,1) (1,0,1) (0,1,1) (1,1,1) (0,0,2) (2,0,2) 
(0,1,2} and (1,1,2). The position of any one item of an array can be calculated: 
X(a,d,c) is at a + b*(ledim;) + c*(Ledim))*{1+dim2) for instance. 

‘All of the above can be checked using simple BASIC; a program of this sort both 
gets up a variable and prints RAM contents: 


10 BBS=100 
a0 FOR J=1084 TO 1090: PRINT J;CHR$(PEEK(J));" ";PEEK(J): NXT 


Line 10 can define any variable; the vatues of J in line 720 will need juggling unless J 
is defined in terms of the end-of-program pointer. 

The length occupied by an array is easy to calculate {the figure is identical to 
that of its own offset pointer}. The number of bytes is: 

$+ 2*NUMBER OF DIMENSIONS + (DIM)+1)*(DiM2+1)*...*(DIMy+1}*2,3, oF 5, 
the figure depending on the array type (integer=2, string=3, real=5). In addition. the 
strings of a string array must be included, and, in BASIC 4, 2 bytes for each string. 
Examples; X$(1000), defined so that each X${n) string has tength 10, occupies 

S + 2 + 1001*3 + 1001*10 = 23020 bytes, plus 2002 bytes = 13032 in BASIC 4. 

A%(50,50}, which holds about 2500 integers, occupies 
5S + 292 + 51°51"2 bytes = 5211 bytes. 


BASIC pointers There are seven principal pointers in Microsoft BASIC. PET/CBM has: 


START OF BASIC (usu. 1025) (40 dec) ($7A) (122) 
END OF BASIC/ START OF VARIABLES ($2A} (42 dec) (STC) (424) 
ENO OF VARIABLES/ START OF ARRAYS [| ($2C) [44 dec) ($7E) (126) 
ENO OF ARRAYS ($2E) {56 dec) ($80) (128) 
START OF STRINGS ($30) (88 dec) ($82) (190) 
END OF STRINGS (50 dec} ($84) (132) 
TOP OF MEMORY (52 dec) ($86) (134) 


The bold figures apply to GASICs 2 and 4; the order of these pointers Is low byte 
followed by high byte, following the 6502 itself. Knowledge of these locations enabies 
the top of memory (normally fixed when the machine ia turned on) to be lowered, thus 
creating extra RAM space protected from BASIC. See WiMEM & LOMEM in Chapter 5. 
Arrays can be erased by changing the pointers: see the ‘Scatter Sort’ in Chapter 5, 
BASIC can be made to start at other locations than 1025, end so on. This program, for 
BASIC>L, reports the current valuca of these pointers within a program. As It stunds, 
two simple verlables (X and FN BE(X)) exiat, but othars may be added earlier ln the 
program and the results watched. The right-hand columa of the table ia BASIC 1. 









































$000 DEF FPN DEEX(X) = PEEX(X) + 256 ® PESK(X+1) 

50L0 PRINT * START OF PROGRAM"; PR DEEK(40} 

3020 PRINT “ND OF PROCRAM/START OF VARIABLES"; FN OEZK(42) 

5030 PRINT ® {LFNGTH OP FROGRAM ="; ( FN DERK{42) = FN DEEK(40} ) 3 “BYTES )” 
$040 PRINT 

$050 PRINT “ END OF VARIABLES/START OF ARRAYS" ; PN DFFR(44) 

5060 PRINT "(NUMBER OF VARCABLES #"; { FN DEEK(44) + FN DERK(42) ) / 74 ">" 
5070 PRINT 

5080 PRINT "' END OF ARZAYS/START OF FREZ RAM"; FN DREK( 46) 


3090 LF FM DREK(44) = FH DERK(46) THEN PRCT * (MO ARRAYS EXIST)" 
5100 PRINT 

SLLO PRINT * START OF STRINGS; PM DEFK(48) 

$120 PRINT “ ZHD OF STRINGS"; FN DEZK( 40) 

5130 PRINT “ TOP OF MEHURY"; FN DERK(S2) 

$140 PRINT 


S130 PRENT "DATA STATEMENT POLNTER"; FM DEEXK(62) 
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Because these pointers mark the boundary between one set of data and another, it 
follows that the upper limit over a range is exciusive, not inclusive. A 32K machine 
has a top-of-memory indication of $9090 on switchon, but thia means that $8000 is an 
upper limit which is not reached, so characters don't appear in the top left of screen. 
These pointers can ali be seen by entering SYS 4 and displaying bytes from 0028 on, 
with .M 0028 0030. 

By defining the variables' area to coincide with the screen, we can watch var-~ 
iables being set up in rea! time. The program prints the current operation on the top 
line of the screen, and awaits a keypress before each piece of processing: 


100 POKE 42,40: POKE 43,128 :REM START OF VARIABLES = $8040 (2ND LINE) 

110 PORE 52,207; POKE $3,135 :REM TOP OF MEMORY 2 $83E6 (HTM RIGHT OF SCREEN} 
120 CLR :REM MAKES POINTERS ALL SELF-CONSISTENT 

120 PRINT "[CL@AR]": POKE 59468,14; REM LOWER-CASE MORE READABLE 

200 Dim ¥A(20) : GOSUB 1000 :REM SUBROUTINE AWAITS KBY (E.G. SPACE BAR) 


210 4=1234 ; GOSUB 1000 :REM WATCH ARRAY MOVE, ‘A' APPEAR 

220 DIM 3T$(20): PRINT (HOME) “S7$(20)": GOSUB 1000 :REM PRINT TO SCREEN TOP 
230 ... ET... - 

1000 GET X$: IF X$e""" GOTO 1000 

1010 RETURN 


80-column CBMs require a slightly modified program if the full screen is to be used, 
and BASIC 1 requires different POKEs in lines 100 and 130 - see table. 

The dimensioning of arrays, and filling with null variables, can be watched; so 
can assignments of all types of variables. Strings fill down from the top of memory. 
and start again near the top when space temporarily runs out. If several different 
atrings are assigned to the same string variubie, FRE can be watched ag it moves the 
most up-to-date value into as high RAM ag can be managed. 


2.4 BASIC syntax 

BASIC is sometimes described as 'English-like'; in fact the resembiance is tenuous. [15 
syntax has to be learnt, Sike that of any other computer language. BASIC is a rather 
ad hoc language, and a comprehensive account of its syntax is made difficult becuuse 
the interpreter allows great latitude in a program. For example, is RETURN or GOTO 
10 valid, if there is no subroutine or no line 10 respectively? How can the correct 
syntax of READ ... DATA ... RESTORE be defined? Is NEW:!*? valid? The usual 
approach la to define the Individual components of BASIC using some form of the Bacx- 
us-Neur notation, but | shail spare my readers this experience. The account following 
outlines the major features of BASIC in a purely descriptive way. 


Numerals and literals These are actual numbers and strings. not variables. Example» 
of the flrat are 0, 2.3 E-7, 1234.75, and -744; examples of the second are “hello”, 
"ABC123", and "$!£/" where the quote symbols are delimiters (not part of the literal). 
The rules which determine the validity of these forma are complex; yenerally, numbers 
are valid If they contain 0-9, +, >, Eand . in certaln combinstions. Thus, imaginary 
fumbers (e.g. 2ir3j) are not accepted, and 3E 2K 1 (i.e, 3 * 1020) ond 1.2.3 are not 
accepted. The only point iikely to cause difficulty is the use of E to mean '10 raised 
to the power ...'’. Strings cen include any CBM ASCII character; tricky characters — 
cen be manipulated with the CHR$ function. However, some characters - 13 (Return! 
and 0 (null) for example - produce unusual side-offects. 


Variables At any moment, a variable must equal a numeral or atring; the default va! 
ven are 0 and the null character respectively. (See Chapter § on CHRS for a discuss 
fon on CHRS(G) and °", each of which can bo conalderad 4 null string). A variabiy. 
as tho name ja suppoxed to impiy, can be changed to other valid valucn. 


Operators {or ‘connectives'} [Binary operators connect two lteas of the same type. BY 
Ing # vingte new item; unary operators operate on n single Item, generating a aew une 
of the same type. The CHM numerle operaters are completely standard, and are ident 
kcal in typo and hierarchy to thone of FONTHAN, The atring operntors and logical 
Operators aro lesa slundard:- : 


Binary Numeric ¢+-*/ Unary Numeric +- 
String = + ~—"" String . Hone, , 
Logical AND OR <=> Logival = =NOT 


‘Dyadic’, ‘monadic!, and 'Boolaan' are aynonyme for ‘binary’, ‘unary’, and ‘ogicn!’. 


. 
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Parentheses Parentheses (round brackets) signal the translator to process the follow- 
ing data ag a unit, completed oniy when the corresponding right parentheses have been 
found. Intermediate calculations are stored on the 6502’ stack. 


Functlons Some of the BASIC keywords are valid only when followed by an ¢cxpress~ 
fon in parentheses; they may be used on the right of assignment statements or as part 
of an expression under evaluation. Numeric functions include SQR. LOG, EXP, and 
SIN; string functions include LEFTS$, MIDS, and RIGHT$. PEEK, although not a func- 
ton in the usual deterministic mathematical sense. has the syntax of a numeric function 
and is considered to be one. 


Expressions An Arithmetic ex ression {s a collection of numeric functions, numerals, 
real and integer variables, connected with operators and parentheses, and always used 
in an assignment statement or with PRINT, PRINT#, or CMD. For example: 

BQR (VAL (Q$(2,3)) + M%) + SGN(Z}*(K>4) 

A String expression is @ collection of string functions, literals and 
string variables, connected (optionally) with parentheses and/or the only string oper 
ator, which is '+'. For example: 

BTR$(25) + MIDS("HELLO”" + ¥$,3,4) + CHRS (N)} 

A Logical expression evaluates to ‘true’ or 'false’; It may contain relat- 

jonal operators {<,=,>) and/or logical operators. For example: 

{A=4) OR NOT (21=%) 
Thera is not a sharp distinction between this type of expression and an arithmetic 
expression, The same routine evatuates them both, which makes possible constructions 
like PRINT 122 and ON 2 4 (PsQ) GOTO 100,200. See Chapter § on AND, NOT,and OR. 


Statements A statement is a syntactically correct portion of BASIC separated by an 
end-of-line marker or a colon from other statements. All statements begin with a BASIC 

_ keyword, or, where LET has deen omitted, with a variabie, There are some peculiar 
eases; for exampte, IF A=B THEN is a statement because its syntax is accepted. (Nate: 
keywords are sometimes called ‘'statements'). Types of statement include: 

Assignment statement LET variable = expression. LET is optional. Here, the 's! 
symbol is used differently from the relational operator 'z', and it is distinguished in 
pome computer languages (e.g. ALGOL) by being written ‘:=' and read ‘becomes ...'. 

Conditional statement IF condition THEN ... - See Chapter 5 on !F. 

Gontrol (or ‘sequential') statement Alters the program's flow of control, GOTO, 
GOSUS, RETURN, ST OP are examples of keywords. 

Input statement fetches data from a device or from a DATA statement. INPUT, 
INPUTS, CET, GET#, and READ are the relevant keywords. 

Loop (or ‘block’ ot ‘’compound’) statement enables many statements to be exec- 
uted in a block: this Is reatly a atructured programming concept, only applicable to 
CBM BASIC in w loose sense to FOR ... NEXT loops and subroutines. 

Output (print'} atatement sends data to tape, disk, screen, or other output 
device. See PRINT and PRINT# in Chapter 5 for an account of formatting, tabulation, 
evaluation of functions, and so on. 

Remark (or ‘comment’) statement In BASIC, REM followed by any information, 
which Tg ignored by the computer but useful from the point of view of documentation 
of the program. Lines which ore never executed perhaps come into this category: 

0 GOTO 100/ 1 VERSION #L/ 100 REM BODY OF PROGRAM never executes line 1.* 

Type conversion stutement converts between string variables and titerals/ real 
variables and numerals? integers and numerals, using such functlons as ASC, CHR$, 
INT, STRS, VAL. 


Program tines are made up from statements. Fach ino ia preceded by a zero byte, 4 
Unk address, and a line number, and terminated bY a zero Lyte, The line ituclf may 
contain tokenised keyworda (ali with thelr high bit set), double quoton, Hterala within 
the quotes, screen aditlag chaructecs with Lhe high bit set, $,%, of ( typo declarntors, 
variables, parentheses, numeric atrings in ASCIE, punctuation ¢;:,), ASCIT strings in 
comment statements and DATA stslementa, and other Item, for example '# an part of 
GET # and non-standard BASIC used with modifled GETCHAR routing, typically !, or 








‘The slash ayebola (/) ‘ere a apece gaving davices, wnadiing. several tines of BASIC or 
machine-code progres to be printed as though only one Line ware occuphed, When thie 
sort of program te keyed in, obviouniy Return takes the place of ‘/'. 


ee ees 
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2.5 Manipulating BASIC and its variables 


Pointers, link addresses and linenumbers An ordinary BASIC program is stored as 
this diagram indicates. The starting address is $0400 (=1024), each line has a 2-byte 
link pointer and 2-byte linenumber, and is terminated by a zero byte. Normaily, no 
zero bytes appear within a BASIC line, and the linenumbers are all different, in OF sk 
cending order, and !ess than $FFOC (=65280). Each link pointer paints ta the next li 
pointer in memory, and the chain proceeds regularly upwards. until a zero link sig- 
nats the end of the program. Any of these features can be modified, either in BASIC 
or machine-code, enabling non-standard results to be achieved. Conversely, such 
functions as renumbering, searching BASIC and compressing BASIC can be written 
when the storage mechanism is understood. Modified BASIC is likely to be more-or-less 
unstadle; it may be difficult to edit, for example. 


START END OF LINE END OF LINE END OF LINES PROGRAM END 
x Taina [pave tame|p|cme| vine | ons se uine|p[.ome]camma]ansse[ole|®| 


The Unk addresses and linenumbers are quite easy to focate in either BASIC or mach- 
ine code; they can also be examined by entering the monitor and reading the memory 
dump from $0400 onward, This BASIC routine illustrates the principles: 


10 A=1025 

90 LePEEK (A) + 256¢PEEK(A+1): IF L=0 THEN END 

30 PRINT "LINK POINTER 1S “ L; 

40 PRINT ° LINENUMBER IS “ PEEK(A+2) + 256*PREK (A+3) 

50 A=L: GOTO 20 
When RUN, A=current link. Lenext link; the program prints both items for every line. 
The machine-code equivalent. iHustrated by this 


outline routine, usesy an intermediate double-byte LDA 28 :4 AND XK ROLD 
address to store link addresses. In ROM, the LOX 22 : START-OF-BASIC 
routines at C$22/ C52C/ B5A3 for BASICS 1/2/4 L1 LDY #01 i¥ I9 OFPSET 
search BASIC for a given linenumber, typically STA 3C :¢4C) 19 A TEMP. 
when executing GOTO. The short program here . §T% SD ; POINTER 
earries out a small part of that eperation, skipping LDA (SC),¥ ;1F LINK'S 2ND 
through the link pointers te the end of the pro- BEQ 12 ;BYTE=0, SXIT 
m. TAX :GRT NEW XR ..- 
Chapter 5 has severel examples of this. See pEY 
for example the ‘tiny renumber' routine, which LDA (5C),¥ 5... AND NEW A 
changes all linenumbers which lie within 4 requested JaP 11 sAND CONTINUE 


range. by poking the new values for the linenumbers L2 BTS 

directly into RAM. As another example, look at 

this BASIC search routine, which prints the linenumbere of all lines which contain 
the contents of the first line (e.g. line 0) of the program. 


62000 A01025: B=25¢;: getO29; X=PEEK(J): REM X18 FIRST CHARACTER OF LINE 0 
62010 P=PEEX(J): IF P=X THEN GOSUB 62500 

62020 IF Pc>O THEN JeJel- GOTO 62010 

62030 IF PEEK(J>+2)~0 THEN END 3: Re END OF PROGRAM POUND 

62040 JaJ+4: A=PEER(A) + B*PEEK(Ae1): GOTO 62010 : REM UPDATE LINK AND J 
62300 Ket :RuM TEST REST OF LINE O FOR MATCH 
62510 Y=<PEEK(1020+R): UF YaQ THEN PRINT PEEX{A+2) + BoPEEK(A+3): RETURN 
62920 IF Y=PEER(J+K) THEN KeX+l: GOTO 62510 

62630 RETURN 


This routine in written without loops, In a form wulted to direct conversion Into mach- 
Ine vode, which ia enormoualy faster than BASIC in thla case. Tho point of the rout- 
ine Is to wean only the BASIC line, while keeping truck of the link polnters; Tae 
62510 prints out a finenumber when all the characters in line GO match some part of 
BASIC. It In necessary to remember the way in which BASIC ln stored in routines like 
thle one; for exampic, & PEEK(1025} will cause all occurrencos of PEEK(1025} to be 
recorded, but 0 BEK( 1025) lx not tokeniaed and wil) probably find nothing. 

The actual cantents of BASIC may be changed In a aystematic way. The whort 
BASIC routine on the next page Insarin carrlage return characters info REM atater 
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ments, when REM is the first keyword in a fine. 


80000 A=1025: B=256 

SOO010 IF A#Q THEN END 

$0020 I¥ PSEK(A+4)<2143 THEN A = PEEK{A} + B*PEEE(A+1): GOTO SOdrO 

50030 POKE A+$,13: POKE A+6,13: A=PEEK(A)+B*PEEK(A+1): POKE A-3,13: GOTO 50010 


It operates by searching for the tokenised form of REM (=143 in decimal), and putting 
three Returns into the REM line. 

Note that arrays in memory can be scanned in & similar way. The only differ- 
ence is that an offset, not an absolute pointer, is used: 


10 DIM NC7),MM(5O), X1$(200), JI%(6) ,Q$(19) 
20 S=PEEE(44)+296*PEEK (45): E=PEEK(46)+256*PEEK(47): REM START, END FOR BASIC>1 
JO PRINT "NAME OF ARRAY: “' ;CHR$(PBEK(S)}; CHRS$(PEEK(S+i)) 


40 OnPEEK(S+2)+256*PEEK(S+3): S=5+0; “ ; REM OwOFFSET 
$0 IF S<E GOTO 30 : REM 3S POINTS TO NEXT ARRAY 


SORT in Chapter 5 uses a machine-code version of this. 

The following pair of BASIC subroutines changes the link ‘addresses of Sines In 
their own programs. The first alters a pointer so that a line is skipped; that line is 
also renumbered 0. It is likely to become visible on editing. When RUN, the hidden line 
ts processed normally, although LIST and GOTO cannot find it. 


O00 A210251 B2256 
1010 INPUT “CONCEAL LINE AFT&R™:X 
wO2u FOR Re LTOLES: IFPEEK Av 2) +B #PEEK (A+3) (XTHEN ASPHEK(A) +B PEEK (AS1) sNEXT 


1025 IF PEFK(A+2) + B#PEEX(A+3)>X THEN PRINT “NON EXISTENT LINE”: END 
1030 XS*A: KEM START LOCN OF LINE X 

1040 YS2PEEK(A) + H*PEEK(A+i): REM START OF FOLLOWING LINE 

OHO KL4PEEK(YS)s XZEPEEKCYS+1)+ FEM INK ADDRESS BYTES OF NEXT LINE 
3060 POKE XS/XL ¢ POKE XS¥1sX2 1 REM LINK ADDRESS STRALULES LiNE AFTER X 
1070 POKE YS+2+03 POKE YS+3,0 + REM AND PREVIOUS LINE iS NUMBERED 9 


This second routine demonstrates how CRUNCH can compress BASIC Unes together, 
making them longer than the normal maximum of 80 characters. It must be positioned 
at the start of BASIC; when it runs. a range of linenumbers is asked for, and these 
{Ines are combined into one longer line by deleting jink addresses and pointers, put- 
ting in colon separators, and adjusting the initiat link addresa to span the entire line. 
lf the line’s length exceeds 251, it will be difficult to edit; it will run, however, in 
most cases, though not if REM is tuo far from the end of the line. 


O INPUT “COMBINE LINES FROM,TO’;L,U; C#1025: B=2sé- BePEEX(42)+5*PEBK (43) -4 
1 LT=PEEK(C+2)+B*PEEK(C+3): PRINT LT; 

Og IF LTcL THEM CPEEK(C) +A*PEEK (C+1): GoTo 1 

3: IF LT>L THEN PRLNT “LINE NOT FOUND": gND 

@ LINK: Caled 

6 Q=PEEK(C): IF Q<oO THEN CeC+i: cote $ 

6 LF PEER(C+1)+PEEX(C+2}20 THEN END 

7 LT=PEEK(C+3}+B*PEEK(C+4}: PRINT LT; 

@ IP LT OU THEN CeC+1: POKE LINK, C-INT(C/B)*B: POKE LINK+1,C/B: GOTO 4 
@ POKE C,ASC(":"): POR JaC+l TO E: QePEEK(J+4) 

10 POKR J,Q: NEXT: E-R-4: GOTO 5 

11+ ~-REAT OF PROGRAM~- 


If the pointera to the atart of BASIC are altered, BASIC can be stored In other places 
than the unual $0400; for example, it could start at $1000, leaving a lurge amount of 
RAM froa for other purposes, Similarly (sve HIMEM & LOMEM in Chapter 5) the point- 
ors to the top of memery can be changed. 

PORE 40,1: POKE 43,16: POKE 4006, 0: 5EW 
Sete BASIC>1 to start at $1000, The zero byte at the very aturt is necesuary; whthout 
it, ?SYNTAX ERROR will be yenornted. Th return to normal, onter 

PONE 40,1: POKE 41,4: POKER 1024,0: MEW 
(NEW, or CLR, Is the cnsieat woy ta ensure the polntars are connintent). A program 
of (hin sort may be naved. with Its machine-code, by moving the start painters back 
to the normal value; tho firat line of the ‘normal! program muat be something Ilke 


we er 


aro 
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O POXE 41, 16:RUN 
which will run the main program correctly. 

The variables themselves may be manipulated: see e.g. VARPTR in Chapter 5. 
The entire collection of RAM variables can be saved as a RAM image; for example, a 
large integer array may be saved and later reloaded, providing rapid access to a lot 
of numeric data. Strings are less easy to handle, because they are not held in the fix- 
ed way in which numerals are. This technique is not very easy, since any change in 
the program length or in the number of variables will cause the data not to match its 
pointers. Reloading is also made more difficult than it might be by CBM BASIC'‘s tend- 
enicy to restart programs which use LOAD. 

When a program is edited, CBM BASIC always resets the polnters relevant to the 
variables. In fact the variables are still present, if the new program is shorter than 
the old; so if the pointers are poked with their previous values, all the variables will 
be recovered; the only exceptions may be strings held within the program and func- 
tian definitions. 


2,6 LOADing and RUNning BASIC 
LOAD or DLOAD followed by RUN is the normal method of running CSM BASIC; the 
only automatic RUN facility is provided by Shift-Stop, which LOADs and RUNs the 
first program on tape or CBM disk depending on the version of BASIC in ROM. Both 
LOAD and RUN are covered in detail in Chapter 5, and DLOAD is explained in Chap- 
ter 7, The overlay feature of each load command, when in program mode, is also out- 
lined, RUN executes some initialisation before entering a loop which processes state- 
ments consecutively. Before every statement, the Stop key is tested, and the end-of- 
program byte is checked for (without this, each program would need END) at the end 
na ponent an dropping meri these subroutines, the execution time of BASIC can 
3 is requires 4 routine, - 
Gcathe fia. x aed e, probably called by a SYS command, to per 
aie Numeric routines are mostly carried out using two ‘floating-point accumulators' 
bytes each, and some other RAM storage areaa in the zero-page. Strings are 
pr tat kink in the top of memory. The 6502 stack is used by GOSUB and FOR, each 
which puts several bytes of data in store on the stack; see Chapter 5. Also, eval- 
eee which include parentheses for priority put intermediate results on the stack. 
A unexpected 9?0UT OF MEMORY ERROR can result if the stack is asked to hold too 
Such data. 
1 PRINT (14+ (2+ (34 (46 (54 (6+ (7+ (B+ (9+ (10+ ¢414(12))3))99)9999 
Causes such an error. The iimits of the stack are determined by a combination of the 
Rumber of GOSUBs, FOR loops, and parentheses at any one time. 
eves Perea Nr oe the CONT pointer is updated. [n this way, when- 
ed, : 
shigent ic: premeide © can resume the program, since a record ts kept of the 


2.7 Optimising BASIC 
hid Principal optimisation problem likely to be met with in BASIC is making a program 
od Mate fast as possible. (The other problem - shortage of space ~- | am assuming to be 
ine ter of correct initial design). Input/ output, to disks and especially to tape, is 
ganic than processing ln RAM; siow printers can also impose a drag on a system. The 
5) peoeran Ituelf can ba accelerated using the methods In CRUNCH (see Chapter 
Breit the subroutine management techniques In GOSUB (Chapter 5), These rely on 
rbd tie of the way BASIC worka to avoid amall cumulative losses of time, GOTO can 
peice ged ensuring that the destination line ie as near the start of the program fa 
CRM @, or has a linenumber whose high byte axceads that of the GOTO line. Some 

: seer thier have a section on thla subject (almost word-for-word identical to a simi- 
theme ee in Apple manuals). Apart from the routlne compresnion methods of CRUNCH, 
delivers significant thmesavers are (1) the une of variables, nut conatantn, and (ii) the 
Wash te autting up of varlablos In the best order (1.6. most popular firkt) at the 

of w program. An a simplo example. 
10 POR AeO TO 8000; B = B » 1: NEXT takue about 15% longer than: - 

Th 10 Bad: Lat; FORA=“0T05000;B=Bei.: NEXT . 

¢ point about using variables ia that the numerical value jis already stored In float- 
ae fe form, so the tlne spent in thé conversion procean Ix naved. Generally, loope 
pie Sly {o maka the most difforence to running-time, and one-off routlies such ae 

roulnes and error messages the least. This program enndles einglo BASIC state- 


a 
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menta to be timed, so the reader can experiment in this area: 
ORAM TO MEASURE PROCESSING TIME WITH EBRSIC- 

NH = 1001 Ti=O: T2-0 
T1 = TI 


| FOR I = 1 TON 
a 


HREM STORE THE TIME ...« 


| MEXT 
1 T2 = TL - Tk RREM ».. SO NOW T2 IS THE TIME TAKEN BY LOOP 30 - 3. 
1T1 = TI 


sREM STORE THE TIME «ee 
1} FOR Ef = 1 TON ; 
1@ £X0123.436 
@ NEXT 
@ 72 = Tl - TE - T2 :REM T2 = TIME TO EXECUTE LINE 19@ AFTER THE COLON. 
1@ PRINT 1080 m T2 ¢ (604N) "MILLISECONDS" 
oo REM YEH AS EIRII ODIO SIIB A IERIE AD IDR ROO IID TR TORII IE EIT TT IRE 
161 REM & EXECUTE @NO TIME COMMANOSS> IN LINE 188 ” 
322 REM 
393 REM 
4 REN 


* * 
™ 
x 
305 REM *® CHECK:- ZERO MILLISECONDS SHOULD APPEAR WITH 10@1 ALONE 
* 
* 
* 


* 


* 
5306 REM * 
187 REM INCREASE THE YALUE OF N IN LINE 160 IF THE INSTRUCTION IS FAST * 
308 REN NB; SEVEPAL LINES OF CODE CAN ALSO BE TESTED WITHOUT OFFFICULTY * 
109 REM # N&: DEFINING VARIABLES AT START AYOIOS SEARCH TIME ERRORS » 
318 REM WN A dH HORE ERO EAE AREA IAEA IOI ERE RRR OP TOR A t 


BASIC<4 has a well-known drawback in the long time spent freelng strings in memory. 

This means that large arrays (e.g. X$(500)), however convenient for storage of easily 

recovered data atrings, are prone to cause prolonged delays; FRE takes about 1 second 
with 100 strings, 10 seconds with 350 and 100 seconds with 1100 - see Chapter § for a 

formula. Chapter 4 has details on minimising these delays. 


2.8 Differences between ROMs 


The major differences between ROMs are listed below, Generally, later ROMs ‘can run 
all earlier programs, but eartier ROMs may not have some features assumed in later 
programs. Programe using machine-code calling ROM routines or specific RAM locations 
are unlikely to tranafer between machines. BASIC 4's two versions, 40 and 90-column, 
are dissimilar in some ways, the 40-column version retaining some features of BASIC 2. 

















BASIC 2 


input buffer $0200 - $0250; more #page pointer 
Tape buffer #2 partly used 

CQ00-FFFF C000-PFFF BO00-FFFF 

Apart (rom kernel addresses, almost all ROM entry points differ (Ch. 15}. 

RAM only (see manuai) Machine-language monitor present In ROM 

Interrupt | 60 Hz 60 Hz [50 Hz (12-inch modeia} 

Other General Improvements (e.g. LIST). 


Olfferences which may affect BASIC programs: 
Kaywords co 
Syntax 
Arrays 
fEEE 

Screen 


BASIC 1 
Input buffer in zero-page 












Differences: 
RAM map 






ROM map 







Monitor 









CO,DS,DS$, & diak commands 











Spaces in koywords vulid* 
Soa DiM (Ch. 5) for bugs 
















Improved 

Fost screen; more editing chr. 
Strings FRE slow FRE fost (nee Ch. 5) 

Tape Data file hugs (Ch. 4) Data file handting improved 

“Ip BAS(C 1, '1F 10-LE THEM PRINT “10”! and ‘EP F OR O GOTO 100’ generate 7BYNTAX ERROR 
ae (LET’ and ‘FOR’ respectively are asaumed. BAS(C>2 does nat scan tokens tn Lhe asee 
wey (hence the need fur GO}. Kowever, in all BASiCes thore la scupe fur ambiguity: 

“TRY <OORKTHEMPRINT ERROR" ‘TPO«TANDUGOTOSO', and 'YeTORU' illustrate thie. 














NOTE THE LEADING COLON, TO ALLOW CORRECTION FOR LOOP PROCESSING #—~ 


La 
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CHAPTER 3: PROGRAM AND SYSTEM DESIGN 
an 


3. General introduction 


This chapter explains some of the techniques and thought-processes required to write 
programs and systems. Chapter 4 provides examples, mostly in BASIC. Chapter LT 
has examples and suggestions involving actual systems; the intermediate chapters deal 
with the hardware and software knowledge required to actually do the job. 

Designing a system is a tricky process which is unlikely to be successful with- 
out a considerable amount of experience, unless a system is fairly small and informal , 
and either unimportant or easy to reconstruct in the event of disruption. The differ- 
ence between small systems and those consisting of many programs operating on alarge 
database, with full validation and erashproofing, and with checking and recovery pro- 
cedures, is enormous. Obviously it is necessary to assess whether 4 proposed system 
ig feasible at all, and the optimum amount of work to put into it. Since this book is 
largely about the PET/CBM, we can leave aside the difficult problems of deciding 
between rival machines. We can also ignore the special problems of programming €x~ 
ternal hardware, for example in process control, which is a minority interest. By and 
large our concern is with a computer, tape and/or disk storage, and probably a print 
er, What oan such a combination of hardware do? Expericnced programmers, naturally, 
already know. For those less experienced, we can subdivide the replies into three cat- 
egories: results which can be achieved easily, those which are difficult, and those 
which are impossible. in the first category we have standard packages. if they exist. 
Sometimes several packages may be able to share data. The absence of programming 
effort does not, of course, guarantee success. Programs requiring ealculations, when 
the formulas are known, are usually fairly easy: anything from architecture to 200_ 
nutrition might be required. Any type of alphanumeric data can be stored and retriev- 
ed, though not necessarily rapidly; dictionaries, tables, price-lists, technical words. 
names, can be filed and recovered, provided the storage capacity of tape or disk 1s 
allowed for. Small business programs, with reasonable crash-procfing, are possible if 
the processing demands aren't large: invoices and mailing-lists for example. Puyroll 
programs are possibie in 4K, in some developing countries. Tidy formatting and out- 
put is not a big problem. Nor are siowish graphics. ; 

The second category includes anything really fast. Graphics; fast searches in 
memory; rapid updating, input, formatting, and output usually require machine-code, 
which is more difficult than BASIC. Any disk reading or writing which uses & key 
other than the record number, and is fast, will need to be thought out earcfully. 
Completely crashproof and validated input is not easy. Data may be coded, abbreviated 
and packed in many ways to save storage space, and so store more data than may 
seem to be possible at first sight. Where many programs operate on the sime data, the 
order in which they are run may need internal checking. Date checking programs may 
be needed which provide an assurance that the data on a disk is self-consistent. Some 
Progroms may require annual updates, or need to be easy to modify. All these things are 
comparatively time-consuming and difficult to write, As the workload increases, the 
viability decreases: sorting the names in a telephone book, performing simulations of 
atmospherle physics, calculating the payrol) of thousands af people, muy be impossible. 
The machine cannot program itself, understand Engtish, correct errors in a specific- 
ation of a system, or work while switched off in a corner. 

Typical complaints (about computer systems generally) are illustented by these 
quotations from a medicat man: ‘They tead to mare clerical work, not luna... produce 
sheaves and sheaves of that printout stuff... VOUs are vory giow: you can't just rend 
@ patient's record, you huvo to type It In... you could lose all the data! ‘The whole 
fot’. And an uxport manager; ‘The biggest disaster ia the so-cailed informal specif- 
icalion, We assumed we were speaking the same language... the program tikes Unys. 
We'd seen programmes an televiaion whore thy results come up instantly...°, Ketulers 
ure often suked for their ‘standard stock euntrol package und PAYE puyrall prekage + 
often Ihexe do not exist. J have slressed the possibilities of failure, eenuse 1 is un 
portent to ronlisa that this can occur, [n practice, the djrer prophecies of miss bust: 
huss Fullures due te micrucomputers have not coma trie: systema which are cleaely 
scien romain unuaed. and (he fiska Inherent in risky systema are nol leker. | dan't 
want to imply, by my mention of this tople, that CBM hardware In unreliable, comparatlye 
figures are unavullabte, and all computera are linhle te hardware prutlema und software 
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bugs, and these may be an unpleasant shack to those accuatomed to the facade of 
gnooth-running efficiency presented by data procesaing departmenta. 


3.2 Designi rograms 


The general idea of BASIC is simple: the program does what it's told, starting at the 
beginning and continuing to the end, occasionally encountering a GOSUB and execut- 
ing @ subroutine, or encountering a GOTO and jumping to a program line. The con- 
ceptual difficulty with programming is the need to underatand what the separate comm- 
ands do. Only when they are more-or-less grasped is it possible to tell che computer 
what to do. As a simple example, consider a set of short reports being printed by an 
ordinary computer printer; at the end of each one, a ‘top of form' command has ta be 
issued, whereupon the paper is shifted in preparation for the start of the next report. 
Suppose some reports take several pages, and the printer has no automatic Facility to 
leave a few lines at preset intervals. Then it is necessary to keep a running total of 
the number of lines printed, and to check this number after printing each line; if the 
total equals a preset value, ‘form feed' is Issued, and the total reset to zero, to be 
used for the next page. Typical complications include lines which belong in batches, 
and are not to be separated, page numbers, running totals, and tltles dependent on 
the tast line of the previous page. In this way, an apparently straightforward task of 
programming can become complex. 

There are many theories on the ‘best’ programming methods. For example, *top- 
down' programming designs the main flow first, then the subsidiary routines, while 
‘bottom-up’ programming starts with the subroutines. But ‘structured programming’ is 
undoubtedly the major buzzword. There are several versions of this, ranging from the 
avoidance of 'GOTO', through the use of nested routines, to the attempt to match the 
structure of the data,og it is filed,with the program. CBM BASIC lacks the syntax to 
apply such techniques directly. but they can be simulated. The object ig te produce 
programs which are easily read, so that in turn they can be changed or reused with 
little difficulty. In practice (in my opinion) programmers’ methods are always ad hoc 
and chaotic, and maintainability of programg ia possibie (if at all) only because pro- 
grams are tidily arranged in routines with heavy commentary. Similarly, flowcharts, 
once regarded as highly scientific, are widely regarded aa obsolete, replaced for the 
most part by pseudo-programming languages. But it is not obvious why one form of 
notation should be superior to another; the sad fact is that any complex program will 
remain complex in whatever way It is written down. For these reasons, [ suggest that 
the reader treats definitive’ announcements on these aubjects with scepticism. 

There are two types of non-iinear program flow: a loop (when the program fumps 
back repestedly to an earlicr point in the program; forward jumps are essentially still 
linear), and a branch (when differing parts of a program are selected according to the 


results of some test. Several flowchart represcntatlons are:- 
[ise S . psser 
Flowchart of brench / casentry 


Condition 
true? 
Flowcharts of loops 


There la a British Standard on flowcharting. For our purposcu it in sufficient to de-~ 
note branches by a dismond (or similar) shaped box, ususliy containing the condition 
an a question, and processing by a rectangular box in which are written details of the 
processing. Arrowed lines indieate tho direction of Now of control, Dutail may be at 
the level of alnygle Instructions, or at almost any fevel of vagueness, depending on 
whether the object ia to present a detuiied or overull picture of the program, [n CBM 
BASIC, «a Joop ls usually of the form FOR A«B TOC STEP D .., NEAT A with an impllud 
count from B to C In stepa of D, Changing the variables within tho loop iH apt to 
prove confusing. The orthodox structured forma of DO WINLE and DO UNTIL do not 
count, but wajt until a conditiun is no tonger truc and a condition becomes true re- 
spectively. Thewe forma can be aimutated ensity In BASIC; fur example, a4 construction 


Ike: = 
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DO WHILE LINECOUNT<50 
PEAPORM ROUTINE TO PRINT LINE AND IMCREMENT LINEQOUNT 


mpe 
can be written in this way (or many others}:- 


FOR Awl TO 1000 
LINEQOUNTSL [+1 
IF Li=S0 THEN A21000: GOTO x 
GOBUB y TO PRINT LINE 
x KEXT 


And the casentry construction can be written as ® series of IF statements or, in situa- 
tione where a variable takes values 1,2,3.... , as ON ... GOTO or GOSUB. With a 
Uttle practice, all this becomes straightforward. When fiowcharting, to avoid tangling 
of lines it {s usual to adopt a direction convention. Typically, the generel direction is 
down the page, with loops branching back anticlockwise and forward jumps clockwise 
to avoid clashes. The diagram below gives typical extra aymbols which may be included 
in this sort of chart. 


(se | 
oS 


These symbols are based on notation for large computers: the disk isn't very like a 
floppy disk, and the tape is a spoot rather than a cassette. But the general idea is 
tlear enough. Other types of chart include thase with subprograms connected by ref- 
erence labels, rather than lines. A page number and label marks each jump and branch. 
This technique is suitable for machine~code flowcharts, which are unlikely to have tidy 
loop structures. The 'Nassi and Schneiderman! notation is topologically identical to a 
flowchart, but is rearranged to increase the space for explanatory detail. It has ‘pro- 
ceas boxeat of four types: condition (normally binary); loop with test after processing: 
loop with teat before processing; and a plain processing box. 


Does it exist in the 
arrey? 
‘Wot found’ Print name, add- 
Foas, comment 


The-e are innumerable techniques, each with local 
variants and modifications, and the purpose of this 
section is to give some idea of the appearance of 
the resulting documentation, Any sizenble program 
will be far more complex than the simple examples 
presented here, and may occupy several piges of 
‘text’. 

The Internal detnit of a program may be doc- 
umented and clarified In various waya. Flratly, 
subroutines may be handled In a systematic way: 
they can be documented (see Chapter 4) and arranged within the program to maximlac 
effleieney (yee GOSUB jn Chapter 5). In principle, standard subroutines sre Ww possib- 
Uhty *, Variables’ numen can be aelected In some aystematic, monniagful way, within the 


Subroutine 
or Module 





> 





er a a ge 
MUSE (Micro Usere In Aecondary Education) has standards intended to enables easy inter: 
conversion of progrseas between aachines. (See @.€. Ed’! Comp'g,duly '40), MN Hempehire 
has 4 book of ‘Btandard Mubroutines’ fur PET/CBM, using Linenumbera 10u00-30000, A 
SGras-Hi1l book hae ‘BASIC achantific qudroutines for all computers’. 








Programming the PET /C8M ~20- 


limitations inposed by the fact that only the two leading characters distinguish between 
names, (See Chapter 2). Line-number maps, including subroutines, can be useful in 
navigating long BASIC programs; and conversely, intricate programs with many GOTOs 
may be deciphered in extremis by simply writing down all the linenumbers in execution 
sequence, perhaps revealing islands of code which are never used. The logical process 
which a program carries out is also depictable in many ways, A condition table is one 
Method (see diagram) which in principle can be drawn up without any programming 
knowledge, to be turned into a program as @ routine task. The patterns of Ys and Ns, 
which should cover all possible combinations of the conditions, correspond to one or 
more actions, marked with 'x'. 


3: Program and system design 


Stock > reorder level? 
Stock minus stock out > reorder level? 
Stock out > stock? 





Issue reorder request 
Part issue stock/ increase commitments 








'Data-structured design’ is another methodology, associated. particularly in the 
U.K., with Michael! Jackson. Its object is to simplify matters by matching file structure 
to program structure. If BASIC compilers come to be widely used, techniques of this 
sort will become more applicable to BASIC than they are at present. Before describing 
(in outline} the tenets of this school of thought, we must clarify the idea of a comput- 
er 'file'. CBM disk and tape files are described in detail in Chapters 6 and # respect- 
fvely, but a few words of introduction are necessary, In the usual office sense of the 
word, ‘opening a file on Mr Smith' means either looking at Mr Smith's records or start- 
ing a new folder of details on him. This is not a computer 'file', In the computing 
sense, a ‘file’ is a collection of many recards, which for convenience have a name ass- 
igned to them, and which are more-or-lesa similar in content. A ‘name-and-address 
file’ contains details not only of Mr Smith. but of many other people. ‘Opening a file’ 
means preparing the computer to read or write individwal records from or to the file. 
A simple example might consist of a file with (a) a header record, i.e. a single record. 
holding perhaps the date on which the file was jast used; (b) a consecutive set of re- 
cords, of which some are to be printed, and others are not. These would be distinct 
in some way; for example, items might be marked as deleted, or ag having fallen beiow 
the reorder level, (c) A trailer record might mark the end of the file, typically hotd- 
ing totals. The diagram shows the structure of this file, with a atandard box notation: 


A structured program to process this file is 
illustrated in the second chart, which gives 
a@ general picture of the processing without 
much detail, The moduics and subroutines, 
if they are aufficiently commented and REM'd 
within the program, ought to muke detailed 
processing falrly easy to follow. Note the 
correspondence between the program and the 
data structure. 
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MODULES 


ae 
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Algorithms An algorithm igs a set of rules which (if the algorithm works!) generate a 
aolution to a problem. Taking care with algorithms will improve the logical accuracy of 
programs and probably their speed and efficiency. Typicai algorithms deal with sort- 
ing. merging, and similar large-scale processing, down to the details of rounding, page 
throws, and date processing. As concrete examples, let's briefly consider five types: 

(i) Linear progremming. This is a technique for maximising a linear combination 
of variables subject to certain restrictions. It is not easy, or necessary, ta under- 
stand the ateps involved, which slowly but surely grind out the solution. 

(ii) Warnsdorf's Rule provides a means to generate complete knight's tours round 
& chessboard. The rule is: move the knight to the square with the fewest exit squares. 
This often (not always) gives a solution. There ig no real justification for the rule; it 
gives an attack on the problem, without an indication of whether its solutions are only 
@ subset of the total of solutions, or of the procedure to follow when the rule finds 
several squares which are equaliy legitimate. 

(iii) Decigion-tree pruning is a technique used in the analysis of games (e.g. 
chess} by computer, where the ‘tree' of moves and replies has a colossal number of 
‘branches’, When any ‘branch’ is assessed as ‘worse’ than some other branch, no fur- 
ther time is spent on that "branch', (The ‘alpha-beta algorithm’ is an example}. 

{iv) Sorting. Dates stored in the form DDMMYY or MMDDYY may be sorted three 
times, by year, month and day. YYMMDD requires only one sort. 

{v) 3-Dimensional 'tic-tac-toee' or (U.K.) noughts and crosses has a variation in 
which the first player to make 4 line loses. An algorithm for the first player is: start 
at the centre, then make all moves exactly opposite to the opponent's. This ensures 
that the first player cannot lose. (It doesn't prove that a draw is impossible). 

Formal logic is sometimes helpful in simplifying complex conditions which have to 
be met: see Chapter 5 on AND, OR, and NOT. 


3.3 Designing systems 
‘Systems Analysis’ has no necessary connections with computers. The approach is to 
examine exactly what you'd want a computer to do, taking particular note of the ‘odd 
10%', or whatever figure applies, of oddments, exceptions, and special cases. Useful 
clarification may result irrespective of computers, the mental effort producing results 
which are unexpected, economical, and neat (in the words of Prof. Parkinson). Trans- 
lation of the result to'a computer may nevertheless be unsuccessful. Typical mistakes 
nelude allocating insufficient space for data, so some figures are too large to fit into 
a file; failure to test the timing of a system, in which case the performance may fall 
off dramatically as data is added; adding new features during development. of a type 
Itkely to increase the number of bugs in the system. (For example, an ‘escnpe' key 
folght be introduced to take the operator back to the start of the system, if the wrong 
Part of a program has been inadvertentty culled. The incomplete data already set up 
May cause unforescen errors). File Inyout is important if any sort of elaborate tech- 
nique is to be used (i.e. anything other than sequential acceas or, with disks, access 
@ relative records by record number), Once a database is act up, apparently simple 
Perationn like sorting on some unusual field, not allowed for in the design, or delet- 
ing or inserting records, may simply take too long to be workable. The aim must be to 
achieve a flexible design, since [t ia all but impossible to think out all the implications 
sat aystem beforehand, and in any case may not be cost-effective with cheap comput- 
A complete system typically has a menu of options: entering a numern! or letter 

at the keyboard calls either 4 new program from disk, or enters a subprogram within 

@ program which holds the menu and sane program responses. in this way, functions 
h the syatem can be partitioned up in discrete, tldy units. A separnte routine muy 
andi¢ cnch of the three operations of adding records, deleting records, and amending 
recontn, for example; another batch of programs might handie Inventory reports, In- 
He reports, outstanding orders, and 40 on, Microcomputer systems are usually 
Balle ne This means that flea ure mod fled at the tlmo data ja keyed In. The alter 
bi ve type of dexign is that of batch systems. These are common in mninframe (Le. 

BR canputers environments, the iden being to store data on file, and later run a pro 
da fa check this data and add it to the currant file, updating it by lhe batch of 
ib ata, In {ho sume way, output can be ‘spooled’, saved on a fite for later printing 
ra ae This ta on efficient way to wae a big machine, alnee Ruceesalona of Joba van 
b HA, anel the computer dovan't waste time awniting Input from tecminols. There may 
© Snaufflctont tape or lak atorage space with small mactines to make bateh process- 
@ ponnible. Note hawever that from the recurlty paint of view, running separute 

. 
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patches may be preferable to direct updates, because, if a check shows that the files 
contain ‘corrupted’ (1.e. wrongly written, scrambled) data. the previous copy of the filles 
and the new data can be re-run. 

The relation between data storage - in RAM, tape or disk - and the frequency 
with which it is accessed ia one of the main features of system design: see Chapter 17 
for examples of this and the related problems of the use of printers for ‘hard copy’. 


Specific computer techniques (i) Data compression and codes. It is possible, and may 
be necessary, to save storage space by encoding data. The following chapter has rout- 
ines to compress integers to half their length, and to combine many on-off flags into a 
single number. 

(ii) Checkletters and checkdigits. These guard against wrong input by providing 
a test for self-consistency, typically for use with a reference number of a client or 
ftem, Chapter 4 has exampies. 

Gil) Sorting. The capacity to sort data and store it in sorted order is important 
in large-scale data processing for two reasons. First, reports, printouts, and lists may 
be required in order ~ typically alphabetic. Secondly, the knowledge that data is sort~ 
ed enables much faster processing to be passible than would otherwise be the case. 
Merging new data with old typically requires the matching of two sorted files; in this 
way, at any moment only two records need to be compared to determine whether the 
new record is to be inserted inio the file, used to update its existing equivalent, or 
ignored temporarily while the main file ig read again. And searching data by the 
‘binary chop’ method - equivalent to opening a telephone book in the middle, checking 
the name sought against the middle name, and continually halving the size of the chunk 
of text which must hold the target name - needs sorted data. Chapter 4 outlines some 
important aspects of sorting. 


3,4 Timing, ‘sizing’, and checking systems 

When considering the practicability of a large system, it ig often worthwhile to write 
programs te generate ‘dummy’ data, to simuiate a full file. This data can be generated 
with the help of RND, with which both numbers and alphabetic strings of data can be 
constructed. (With CHR$S in the case of strings}. By testing for inequality, strict 
ascending or descending sequences are casy to simulate. In the light of teats on this 
data, improvements in the logic or file-structuring may be suggested. 

Esthnating the storage capacity to run a system ia relatively straightforward: in 
the simptest case, all records are the same length, so the product of the maximum 
number of recorda and the record-length gives the solution. This figure can usually 
be reduced by data-compression techniques, at the cost of extra programming time. 
Sequentia! files, In which records can differ widely in length, obviously occupy space 
in proportion to the average record length. Disk systems usually reserve some storage 
for their own uperating system, to hold directories and so on, and this must be taken 
into account if space is short. !n addition, the pair of disk drivey in most systems are 
operationally distinct, so that the data may have to be held in a subdivided form on 
two (or more} diska. When this happens, it ls of course important to ensure that each 
diak independently has sufficient room for its own quota of information. 

Testing systema is not particularly easy. {See Chapter 17 on this subject), The 
writer, however, docs at least have informed knowledge which should ease the pln- 
pointing of likely errors. On the other hand such knowledge may simply result in un- 
conscfous or conscious avoidance of areas known to be suspect, For this reason, the 
user Is often asked to supply test data and try it in the system, and to check that its 
resulta are correct. This proccsa will often expose agsumptiona whichthe programmer 
han wrongly made, but It ls unrcusonable to expect guch testing to be thorough. There 
may be parts of programs which ure not tesled; and systematic orrora may not be re 
votled, becouse the combinstions of datn which show up the erroc happen net io bar 
entered, Systematle errors, in which, for example, every 44th record ig last, or rec 
orda of length 254 are corrupted, or items on an invoice after the tenth ara duplicaled, 
are nearly always caused by programming errore. Unfortunately the triggering combin- 
ationa of cirevmstences may be sulflusentty complicated te produce errars appsrently at 
random, Apart from teatlng every part of cach program ot Jungt once, and ensuring 
that test data glyea consistently correct output, commercial programming practice Is to 
try to minimise program wrrork by insisting on atundicd methods, heavy documentation, 
and ‘walkthroughs’. The latter are a kind of group critleiam of a programmer's deaign, 
an a result of which the progrommer [4 supposed to improve hia or her program, The 
effrctivenoas of auch methoda remains in some doubt. 
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CHAPTER 4: EFFECTIVE PROGRAMMING IN BASIC 





&.3 Specific BASIC problems and solutions 
This section deats with the following topics: 


4,1.% Subroutines end documentation 4.1.2 Checkdigits and checkletters 

4.1.3 Codea 4.1.9 DATA: processing steps; relocation 
4.1.5 Date processing a,1.6 Error messages 

4.1.7 Hard and soft coding 4.4.8 INPUT 

4.1.9 The key board buffer 4.1.10 Numeral packing and unpacking 
4.1.11 Rounding 4.1.12 RAM data storage 

4.1.13 Searching 4.1.14 Sorting 

4.1.15 String handling 4.1.16 Validation 


S107 Arrays 


LP Subroutines and documentation Subroutines are used to handle an enormous 
variety of processing tasks: setting scrolling windows on the screen, printing error 
messages. inputting and formatting data, reading passwords, reading a record from a 
disk file, and so on. [f they are to be usable as standard subroutines, a certain 
amount of documentation is helpful. Tne example converts a hexadecimal number into a 
decimal , and prints the answer. All the variables used by the subroutine are listed. 
with an example or two to illustrate the method of use. [f the subroutine itself called 
other subroutines, these too would be listed. Note that the documentation occupies far 
mote space than its routine. : 





550 REM®#* ONE LENE HEXADECIMAL TO DECIMAL CONVERTER *** 


335 Bey 

ie RIM «CONVERTS STRING OF 4 HEX DIGITS INTO DECIMAL NUMBER AND PRINTS RESULT 
65 REM USES J, L, LX, L$ 

570 Rew ALL THESE ARE ALTERED &Y THE ROUTINE 

S75 Rew 

0 tm EXAMPLE OF USE: 

85 2m L$="ABCD" : GOSUB 600 : PRINTS 43981 

$90 Ram 

395 ney 


$00 Led: PORJ=1 TOA: LI=ASC(LS) 1L2eLZ~4B+(L 2964) 47: LS=MID$ (LS, 2): Led 6ML-4LZ: NEXT: PRINTL: RETURN 


4 similar decimal-to-hex conversion routine follows; this uses the same four variadles 
but the relevant variable on entry is L, not L$. , 


500 L=L/4096 1: FORJ«1TO4: LIL: LS=CHRG(484+L2-(L2>9) #7) PRINTLS; : Lol 64(L~L2) c NEXT: RETURN 


4.1.2 Checkdigits and checkietters are (usually) suffixes, computed by an algorithm, 
. are appended to Important alphanumeric data. Typicaliy, the data involved is 4 
Teference number or some key number In a system. The composite data in made intern- 
re consistent, so that keying-in errors can be detected, An an exampic, consider 
Rternational Standard Book Numbers (ISHNs). These consist of 9 digits followed by a 
Checkdigit of 0-9 or X. The §$ digits are codes for the publisher and the title: the 
Sheckdigit is computed by multiplying each numeral in turn by 10,9,8,...4,3,2 and 
adding the result. The remainder after division by 11, when subtracted from 11, is the 
checkletter (except that 10 becomes X, and 11 becomes 6). Ft ls true that any ten 
Mandom numerais have i/11 chance of forming a valid ISUN, so the system |x not fool- 
hai But the point ts that the moat common Input errors are protected from entry to 
@ system, if tha computer Ix programmed to test the checkletter. There are two 
yous typing errors: the first is the ontry of a completely wrong sing: value (e.g, 
atead of 1), and the second is the transponition of two adljucent keys, Bucnuse of 
be system of weighting, and the uso of the prima number divisor, olther of these mia- 
lettece? reper Madigan (ea aerials asnigna 24 charnctora, A-W, ag check~ 
, on the fasuit o ¥inle i : 
Or beeen aK! an ad bopaniy: yn by the prime number 23, Aa a refinement, 
“ea Heenuae thha form of vullcdation in enay to Implement with computers (it ia too 
Sika for human opurntors) a checkdigit ayatom may be well worth Implementing; 
7 out it, whale acts of data may be minkeyed because of some misunderstanding about 
@ layout of an item number or cuatomer number. 
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If ISBN$ is a string of nine numerals (without spaces), this routine computes the ISBN: 


10 CTO: FOR L=1 TO 9: CT = CT + (12-L)* VAL (MIDSCISBNS,L,1}): NEAT 
20 CD$=STR${11 - CT + INT(CT/11)*#11): REM LL MINUS REMAINDER OF CT OIVIDED BY 1% 


20 IF VAL(CD$)211 THEN CD$=" 0" : REM ALLOWS FOR CBM'S STRANGE STR$ 
40 IF VAL(CD$)=10 THEN CDS$=" xX” 
50 PRINT ISBNS + CD$ : BEM FULL ISBN 


4.1.3 Codes. BASIC logical functions use 16 bits in all. If we forget the negative first 
bit. we can hold up to 15 on-off flags in a single real or integer variable. We can test 


any single bit with: 
If PL AND 2TN THEN... :REM WHERE N = 0 TO 14 


And we can reverse any bit, leaving the rest untouched, with: 
FL = FL - 27H *(2*¢( (FL AND 2tH)<0) + 1) 


Thia technique is useful in storing, in a compact form, data which might otherwise be 
written to a file as 'Y’ or 'N', or some other pair of alternatives. 


4.1.4 DATA: processing steps; and relocating DATA subroutines. The following coin 
analysis program, which converts a number of wages/ salaries into their breakdown by 
notes and cain, shows one method for dealing with irregular steps: the values, of 
which there are seven here, are stored in an array: 
10 DATA 7,10,5,1,.5,.1,.05,.01 ;REM 7 U.K, DENOMINATIONS 
20 READ NUMBER OF DENOMS: DIM CN(NU), QU(NU): REM COIN/NOTE DENOMS AND QUANTITIES 
30 FOR Jel TO NU: READ CN(J}: NEXT  :REM READ DENOMINATIONS [NTO ARRAY 
40 INPUT “NUMBER OF EMPLOYEES”; EMPLOYEES: DIM SALARIES OF (EMPLOYEES) 
SO FOR J=1 TO EM: INPUT SALARY OF (J): NEXT 
100 FOR Jwl TO EMPLOYEES 
110 FOR K=1 TO NUMBER OF DENOMS 
120 XH=SAL(S)/CN(K): SALCJ)=SALCI)-RE"CN (KE): QUCE)=QU(E) +23 
130 NEXT; NEXT 
200 FOR J=1 TO NU; PRINT CN(J) "=" QUCJ): NEXT 
Strictly, to avoid any possibility of rounding error, line 50 could include 
'BA(J) = SACJ) + CN(NU)/2: NEXT, adding in this example tp to each salary. Line 
10 can be replaced by any currency combination, provided the denominations are in 
order, and the first DATA value is the total number of denominations. Note that DATA 
statementa can be made relocatable; this avoids problems which can arise when new 
DATA statements are inserted before existing ones. READ operates purely sequentially, 
go the Introduction of new duta may spoil previously correct routines. One method ls: 
10000 REM STANDARD SUBROUTINE WITH ‘DATA’ 
10010 RESTORE 
10020 FOR L=l TO 1£10: READ X$: IF X$<>"SEZARCH M/C” THEM NEXT: REM READ 'TIL NAME 
10030 REM *** READ DATA HERE #48 
10040 RETURN 
10080 DATA S¥ARCH M/C,100,0,45,34,66; REM ETC. 





4.1.5 Date processing. We have three date routines here: the first calculates the day 
of the weak given the date, the second calculates days-betwean-dates, and the third 


1 REM seapeneeroeeunen ZELLER’S CONCRUENCE Fa teenesernennnes SHER HHEH EH EY 


2 REM * FINDS OAY OF WEEK FOR ANY DATE * 
3 REM PPOVUTTTIPI TIT TTT rE tlie 
4 REN ® ‘CENTURY’ IN ITALIAN SENSE: 19 FOR 20TH CENTURY + 
3 REM 8 IF WE ASSUME 19: LINE 50 GECOMES: * 
& REM « 50 J = INT(2,60M - 6.19) + D+ ¥ sEINT(Y/4) ~ 34 * 
7 REM *# * 


@ REM * DATES MAY BE TESTED FOR IMPOSSIBILITY BY AN ADDITIONAL ROUTINE # 
F HEM ROAR Rew RED EEH NH PRES EEREN EERE SEEKHREEREPRESORERSH OREN HR ER RSH EOE ES 


10 DATA SUN+ MON, TUE> WED: THUs FRI» GAT 

20 FOR Jo» 0 TO 4: KEAD DstJi:1 NEXT 1REM TABLE QF DAYS OF WEEK 
30 INPUT "DAY: MONTH, YEAR» CENTLY" # Oe Me ¥eC 

40 M = Ma2) IF MCL THEN MeMed 2) Ye¥-1: REM LEAP YEAR ALLOWANCE 
SO J = INT (2,60m - 1193 + D+ ¥ @ ENTIY/4) » INT(C/4) - 2aC 
60 Je J ~ INT(SS7) 07 

70 PRINT D@fJ> 


¢ 


ee ee ed 


ee ~ 
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is a short validation routine, which checks that a combination of day, month and year 
is valid, allowing for leap years (but not for 1600, 2000 etc. not being leap years). 


ROUTINE TO CALCULATE NUMBER OF DAYS BETWEEN DATES 


10 VATA 0,31+ 59: P05 120s 151. 181+ 212) 243) 273; 304,334: REM DAYS ELAPSED 

13 DIM O(12) 

20 FOR J=1 TO 12: READ Dt(J): NEXT: REM DAYS ELAPSED BY MONTH? NOT LEAP YEAR 
9? REM #98 NOTE U.S. USAGE 1S MD» Y BUT U.K, USACE IS Dim ¥ wee 

100 INPUT “DATEL") Ret Ye tGUB 2NGO 

103 DX = DE 

110 INPUT “BATE2*%: Dom ¥: GOSUB 2000 

115 DY «© DE 

116 PRINT DY-DX 

120 GOTO 100 

L991) EP Fk ee OEE EEA EERE EEA OTR RED EST EREE RAR EEAR ROHR RAED EORE DRS 
1991 REM * DAYS ELAPSEG BETWEEN DATES SUBROUTINE. THIS FUNCTION COMPUTES 
1992 FEM ® DAYS SINCE ON ARBITRARY EARLY DATE —EN THE CENTURY? USING * 
1993 REM # DAY OF MONTH + DAYS ELAPSED DURING YEAR + DAYS IN CENTURY * 
1994 REM # WITH CUSRPECTION FOR PAST, AND POSSIBLE PRESENT, LEAP YEARS. rt] 
LPSS REM i ee ee Ee EAE RARER 
2000 DE = BD + DUM) » 3a5eY + INT ((Y-21)/4) - CCINTCY/4)8#42¥) AND (M927) 
2010 RETURN 


6200 OK=-1 AND ¥>82 AND Y<85 AND M>O AND M<13 AND D>O :REM Y,M,D INTEGERS ONLY 
6210 OK=O08 AND D<32+(m=4 OR M=6 OR M=9 OR Mall} + (M2) * (3+ INTCY/4) *4eY)) 


Line 6260 tests for a year of '82 to '84; cbviously other values may be substituted. 


4.1.6 Error messages are used to signal to the operator that an error has been made. 
This short routine prints the message in reverse at the bottom of the screen, then 
deletes it after a short delay. EM$ holds the message, (e.g. ‘IN SALES CODE’ or 
INVALID DATE'), which is preceded by *** ERROR on the screen: 

$2000 ram ** error aasseqe (mox.iengrh 19} with delay toon end remove ** 

12003 pr Int" (home| [down |i oo0n{ [downi";: tor al told: print ir ight’ Ldcw) Idown 1"; snext: print 

“lrevslP** ERROR MemS™ (rvsol"; 

12010 for [=] fo 2500: next 

12020 fort=ltalan{em$)e1 lige inti lett) [lettl"; saewt 

12023 return 


§.1.7 Hard and soft coding. ‘Hard coding' means that important parts of a program use 
constanta; ‘soft coding’ mcans variables are used. Soft coding is usually easier to mod- 
ify, but slightly more trouble to write. See the second example under MID$ in Chapter 
$ asa specimen, Section 4.1.4's coin analysis program, in which a simple change in a 
DATA statement can convert a program to run with any set of currency denominations, 


illustrates the same lesson. 





4.1.6 INPUT of data, Chapter 5 (under INPUT) and Chapter 2 outline the problems of 
the ordinary INPUT statement, and incitude cures, notably for the crash when Return 
alone is pressed. (The easiest solution ig POKE 3,1 or POKE 14,1 or POKE 18,1 for 
BASiCs 1,2, and 4 respectively}. : 

In order to input commas within atrings, claborate techniques using GET are 
Necessary, of which the following [s an example, When GOSUB 70 Is called within a pro 
tam, « reasonably crashproof input resuita (with @ flashing cursor), returning the 
string as 225. Line 78 allows for the ‘detete’ key. Ae wo xholl sea on the next page, 
this subroutine ia a very smail-acoie version of a completely watertight INPUT. 

69 REM #* SPECIAL INPUT ROUTINE FOLLOWS, WHICH RETURNS STRING 722@ #2 
70 270 = "71 POKE 548+0 $ REM LOCRTION®IGT worm BASIC 2 di BASIC Ay {FLASH cutsot), 
72 GET ZAS1 IF ZAee"" THEN 72 

74 IF aSCUZA®) © 13 THEN PRINT” “te POKE $44.13 RETURN 

Je IF ASCO 7A8) = 20 THEN COTO 54 

78 Tie © ZZt+ZAS 

@O PRINT ZAtr 

82 COTO 72 

4 IF LENGZZ@) > 2 THEN LIO«LEFTO(IZG,+LEN(ZZ@)-1)1 GOTO 8O 

O4 IF LENCZZ9) = 2 THEN ZZae"" » GOTO 80 

$4 GOTt 72 . 
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The BASIC routine on the next page (not for the feint-hearted!) is a successful input 
routine which [s fully parameterised and has the following characteristics: 
VARIABLES ‘FF’ prefix refers to acreen foruat: 
FTSTOTAL NUMSER OF ITEMS TO BE INPUT FROM THE SCREEN 
FC=NUMBER OF CURRENT ITEM; ALWAYS ¢= FI k FL=LOWEST ITEM IMPUT 
PHS(), FVS(), FL&¢), and FS$() hold horizontal position and vertical 
position of start of item/ maximum length/ type of field. The ‘type’ 
may be a string (°&"}, integer ("I"), or 2-decimal point number ("NN") 
'J' prefix refers to input from screen: 
JH, J¥, JL, and J$ = current horizontal, vertical, length, and type. 
713 ie o eingle character, J] 1ta ASCII value, and J8$ the current 
input being built up. J$¢) holds the array of FT inputs from the 
screen. Finslly, JD ia a decimal-point counter. 
SUBROUTINES 100 BTAB & YTAS USING JH & JV COORDINATES; SES CHAPTER 5 

120 GET NGN-INITIAL CHARACTER WITH FULL VALIDATION 
140 WUMERAL PROCESSING ROUTINE (ENSURES DEC, PT. CORRECT) 
160 GET IMITIAL. PERMITS USE OF ‘<* AND ‘7' FOR BACE/FORWARD STEP 
190 REPRINT 2 D.PT. NUMBER, ADDING '." AND ZEROES iP ASSENT 
400 PRINT 'CURSOR’, A SIMGLE GRAPHICS CHARACTER 
2420 DELETE SINGLE CHARACTER, REPLACE WITA SPACE 
450 ** INPUT ROUTINE ** 
300 PROCESS STEPS: "<' BACK, '>" FORWARD, WHERE POSSIBLE 





The length of each variable is defined, so screens of the sort illustrated in section 
9.3 can be used - there is no need to follow each input by a blank Une. Short dem- 
onstration routines (below) show how the routine is used. Unfortunately, flexibility in 
input is not very easy to achieve. The routine ignores characters which are not num- 
erals, alphabetics or punctuation. The double-quote (") is ignored, and must be re- 
placed by the single quote ('}, because of problems which may arise in strings which 
contain a quote. All upper-case keys are ignored, except for alphabetics; shift-~space 
is converted to space, and shift-return to return. In this way, fields which are to be 
compared or searched, which may appear different to the computer because space (AS- 
Cll 32) is held differentty from shift-space (ASCI1 160), are held correctly, and shift- 
return, which typists naturally regard as identical to return, is trested as a normal 
return, The ‘cursor is a static graphics character, which does not flash. {t can be 
contralled by the keys '<' and '>', which step through the fields on the screen either 
back or forwards, The cursor control keys are not used, since they are unfamillar to 
typists. The previous values entered in each field are displayed, to be overwritten by 
new vajues lf desired (but not otherwise), which speeds input. Finally, input of integ- 
ers allows only 03%; input of strings allows ali alphanumerics and punctuation marks; 
and input of real numbers assumes two decima) places, and will not allow input which 
infringes this. For example, if the length of a number is specified as 6, 999.99 is the 
largest number which may be input; the attempt to enter 9999 will be disallowed, The 
decimal! point. followed by 00, is automatically inserted if omitted. 

The first part of the example program defines six Inputs; these are (i) 4 single 
lettar, which must be A or B; (li) three integers of maximum length 2, which make up 
a date; (iil} a string of length 25, perhaps a name or comment; (iv) a string of max-~ 
imum tength 3, which, if 'YES', causes the screun of data to be accepted, and process- 
ing te continue, (Otherwise, '<' ia used to go back ta amend some entry). In practice, 
thirty or s0 separate entries can be made easily from 4 single screen. 


10000 DATA 4,1,17,1,8,9 :REM TYPES, NOTE THAT N=] DECIMAL PLACE NUMBER. 

10010 FOR JeO TO 3; READ FI9(J): NEXT i REM PILL ARRAY OF TYPES 

10020 DATA 1,3,2,2,25,3: HEM LENGTHS OF EACH [NPUT 

10030 FOR J=-0 TO $: READ PL4{J): NEXT | REM FILL ARRAY OF LENGTHS 

10040 DATA 20,10,13,16,4,3 :REM HORIZONTAL START POSITIONS = TYPICAL YALUES 
10050 FOR Ja0 TO 3: READ FHR(J): NEXT :REM PILL ARRAY OF HORIZONTAL POSITIONS 
10080 DATA 2,5,5,5,10,24 REM VZRTICAL START POSITION - TYPECAL VALUES 
10070 FOR J=0 TO 5: ABAD PVECS): NEXT <AEM FILL ARRAY OF VERTICAL PORTTIONS 


Thia routine muat be run before any input takes place. A further subroutine prints 
the screen dotails from which the Input will bo made; again, see acction 9.3 for a 
sercen fayout, which Incorporaten variables, Assuming the strings ara nAtored in the 
array J$(), as in the example foliowing, the screun printing subroutines looks [lke 
thie: 


} 
i 
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200 MEM STAB, YIAB USING JH AND JV COORDINATES; THEN RETURMA 
120 GET J38; tF J1S="* THEN 120 
122 7) = ASC(I1$) 
124 Ip J1>t27 THEN IF J1¢193 OR J1>21B THEN 31971-12037 1$eCHRS(J1) 
126 IF J1 © 13 OR 21=20 THEN RETURN 
128 IF I4e"S* THEN IF J1¢32 OR Jie34 THEN J1$*"":RETURN 
130 Iv J$="I° THEN IF J1¢4@ OR J1>57 THEN J1$0°"; RETURN 
132 IP J$="N" THEN GOSUB 140 
134 RETURN 
140 IP 3146 OR Jt>S7 OR Ji947 OR (ID>OANTAID=LEN(IS$)~2) THEN J1$ = °" 
142 If JD>LEN(JS$) THEN JD¥0 
144 IF J1=46 AND JD<=LEN(JS$} AND JD>0 THEN J1$0*" 
146 tF J1=46 AND JD=0 THEN Jb=t+LEN{(JS$) 
148 IF J1*46 AND JD>JL-2 THEN J1g$="" 
150 IF J1<>46 AND JD=0 AND LEN(JS$}>JL~4 THEN Jt$="* 
t52 RETURN 
160 GET J1$: IF Jig="* THEN 160 
163 SI=ASC(ITS): IF 71>127 THEN T® J1<193 OR 319218 THEN JisJt-t28: T1S=CHRS (It) 
166 IP Ji=13 OR Ji=20 OR J1"60 OR J1=62 THEN RETURN 
169 IFJ$="S"*THEN IF 31632 OR (71> 127ANDJ#¢160) OR J1>223 ORJISI4THEN JIG = “* 
172 IF JS="I" THEN IF J1<48 OR J1>57 THEN J1$="* 
175 IP J$=°N" THEN IF (J1 «> 46 AND J1<49)OR 31957 THEN J1$ = "" 
178 IF J$«"N" AND J1=46 THEN JD* 1 
181 IF J1$="" THEN 160 
184 RETURN 
190 LF JD=0 THEN JS$=JS$+".":PRINT"."3 :JD@=LEN(JS$) 
192 IP JO>LEN(JS$}-2 THEN JS$=7JSS+"O": PRINT"O"7: GOTO 192 
194 IF LEN(JS$)<IL THEN FOR L * LEN{JS$)TOIL<1:JS$=" "+7398; NEXT 
196 RETURN 
200 PRINT" (LEFT) (REVS) 4[RVSO] "7: RETURN 
220 GOSUB 100: PRINT’(LEFT) *:: RETURN 
247 REM 
248 REM ** INPUT ROUTINE FOR STRINGS, INTEGERS, © 2 0.7. WUMERALS 
249 REM 
250 JS$=*": ID=O; INSFHBC FC): JV=FVO{PC)1 JL=FLO(FC): J$*FS$(FC} 
253 GoSuB 100: GOSsUB 200: GOSUB 160 
256 IP Ji=t} AND JSS="* THEN GOSUB220:GOTO250 
259 Ir J1=60 OR J1=62 THEN GOSUBI00:GOTO25a 
262 Ie Us$="" THEN POR L * 1 TO JL:PRINT" “s:NEXT 
265 Ip JS$e"" THEN POR L = 1 TO JL: PRINT" [LEPT] "3 :NEXT 
266 Ip 310173 ANDO J$="N* THEN GOSUB 190: GOTO 277 


271 fF J1=13 ANO J$="I1" THEN GOSUB 194: GOTO 277 ae 
274 [¥ J1#13 AND LEN(JSS}<JIL THEN POR L = LEN{JS$}TOJL-11JS$=76$+ sHEXT 


277 IF 31913 THEN GOSUB 220: RETURN 
280 IF 31 = 20 THEN IF LEN(JS$) < 2 THEN PRINT "(LEFT] [LEPT}": GOTO 250 
283 IP J1 = 20 THEN US$ = LEFTS(JS$, LEN(JS$) -1}:PRINT “(LEFTS [LEFT]"y: GOTO 295 
286 IF LEN(JS$)>=UI. THEN J19=** 
789 Jag © JS$ + I$ 
292 PRINTJ1$; 
295 GOSUB 120: GOTO 268 
300 Gosum 220 
305 1F (PC=FL AND 31960) OR (FC*?T AND Jt<62)THEN ARTURM 
310 Ip Jt=60 THEN PEINTIS( PC): FC=FC-1 
31S Ip 31 =62 THEN PRINTIS{(FC}: FC=FCHI 
320 RETURK 
Parameterised crashproof ‘INPUT’ routine 


ry i A 
2000 PRINT “{CLEAR][RVS] TITLE (RVSOFF] 
2010 PRINT : PRINT " ENTER TYPE (A or B): “5; JB(O) 
2020 PRINT - FRIST : PRINT “ DATE: “; J$€1): J8€2); 2903) 
2030 PRINT ; PRINT : PRINT “(RVS} ENTER FULL NAME:~ (RYSOF?P)": PAINT " rt Te 
2040 PRINT [DOWN] [DOWN] ... [DOWN] Chack: Katry OK? " 


Thla method la useful where repeat entry of data is wanted. If the data ia one-off, or 
the previous values aren't carried ovar from entry to entry, the screen will be similar, 
but the axpressionn In J$() will be omitted, as J$(5) Ia here (because its only functlon 
is to wait for ‘YES'}. 

Finaliy, in wddition to these preliminary routines, the actual input itrelf la maile 
by 9 loop; thin Is necessary to permit free movemont between Flelds during input. The 
Sxampie should make the process, and the inbuilt possiblity of extra validation in add- 
ikon to that by typo, reasonably clear: ~ 
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:REM PRINT SCREEN 

1040 Fos0; Fr<5 7HEM SET LOW/HIGR LIMITS 
1020 GOSUB 250; Of=-2 !REM GET INPUT FROM SCREEN 
1030 IF FC=0 TREX IF JS$<>"A" AND JS$<>"B" THEN OK=0;REM VALIDATES FIRST 1TEM 
1040 JF FCal THEN DD$=JS$ REM DDANYY ASSUMED HERE 
1050 IF FC=2 THEN D$=JS$ REM VALIDATION ROUTINE CAN 
1060 IF FC<3 THEN DY$=J5$;: ;REM BE USED (SEE 4.1.5) 
1070 IF FC=4 THEN GOSUB $00 !REM SOME SORT OF VALIDATION, SETTING OR=0 OR -1 
1080 IF NOT OK THEN GOTO 1020 ;REM REINPUT IF NOT OK 

1090 IF FC=FT AND JS$="YBS" GOTO 1500 :REM EXIT AT BOTTOM OF SCAEEX 
1100 IF FC=FT THEN GOTO 1020 REM CARRY ON [F NOT "YES" 
1110 J$(PC}=J3% REM STORE VALUR IN J${} 
3120 Fe=Fc+1: GOTO 1020 : REM CARRY ON WITH WEIT ITEN 
1500 AEM CONTINUE PROCESSING WITH FULLY-CHECKED DATA 
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1000 GOSUB 2000 


Single-character input fille RAM remarkable rapidly, so BASICs earlier than 4 will give 
trouble with memory-freeing if there are many strings in use. (See FRE, and Chapter 
2), Suppose we input ABCD. Two sets of strings build up in memory, so RAM looks 
like this: ABCDDABCCABBAA, where each individual GET takes one byte, and each 
composite string takes up one more byte than it did previously. A little algebra gives 
in(n¢3) bytes for a string of length n. So a 25-byte entry uses 350 bytes. At this 
rate, automatic FRE in memory occurs often. If this is a problem, as it may be when 
using BASIC <4, palliatives vary from restructuring the program so that data ia held in 
RAM by poking and peeking, to holding several strings as one, separating out the 
individual strings with MID$ when they're needed. (If the number of strings is reduc- 
ed to one-third of its previous value, garbage collection is about nine times faster).An 
aiternative is to temporarily dissociate the bulk of string variables: In BASIC 2, this 
means the contents of ($34) are replaced temporarily by those of ($30), moving the 
‘top of memory’ to the ‘bottom of strings'. Only those variables used in the routine are 
affected by FRE, which is usually much faster. To recover the remaining strings, the 
original top of memory pointers must be replaced. The addresses in decimal are 52 and 
$3 (top of memory') and 48 and 49 (‘bottom of strings’). BASIC i's pointers are diff- 
erent (see Ch. 15). NOTE: see Ch. 17 for Commodore's ‘Standard dato entry environment’ 


4.1.9 The keyboard buffer is dealt with in Chapter 8, section 3.8. Chapter 5 aiso 
as gome examples: see AUTO and DEL, amongst others. This example ia a routine to 
convert machine~code into DATA statements, for later use ag part of a machine-code 
loader. After the input of the start and end addresses - obviously necessary - and 
the starting linenumber, data statements are printed on the screen and incorporated 
in BASIC In direct mode. The key to the program is to note that line 60030's END does 
not actually end the program; a [HOME| and two Returns are forced into the keyboard 
buffer, and since the screen holds something ‘ike this: 


630000A149,0,133,148,169,32,153,2,165,9, 
201, 60,176, 86,165,1,201, 50,176,680, 169 
Le 63000+1; s= 847: £903: goto 80000 


on END, the cursor is homed and two returns entered; the effect is {dentical to that 
achleved by entering these three keys at the keyboard. Values are for BASIC>1. 

I pe lnt*feleer1OATA STATEMENT GENEHATOR : 

10 taput*ster? location" ys 

20 taput"end Aguat lantie 

WO laput"linenumbar®; 

HOOD prdnrHi clear f™aidbCateSE lb, 2>8dA; 1qapeek (2419256 "penn { 55) 


60016 torjes toe P 
40020 J fpostOstpeeht IM de i Tenens inet (lel tl trae tor [home| [down |idawadierl eli nas tiee%e 


“sqoto" 
60080 i tessibroneant 1G OT thangs 25, 1 I: eukei74, t3spoeeh25, 131 pokel 54, Jiend 
60040 printmidits chCgeenif)),297,") 
60030 nnat 
60060 print ltettt *spomes 25, MF raakehi74, (51 p0ka 145, 21004 


4.1.10 Numeral packing snd unpacking In a space-saving mensure, sometimes uacfiul 
when disk apace In Jinilted. Tf [x also rather time-consuming to implement, and slows 
down the program's running ta some extent, Two complementary sxubroulines (next 
Pugo} convert a numera) string (e.g. "12145"), hold an NS$, inta wm packed form NPS, 
and vice-veran, bh effect tha number In stored to bane 00, Lines 40 and 410 contaln 
32; the object of thin Is to avald some codes, a.g. CHRS(O} and CURM11), which may 
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not store successfully. 
1, UNPACK PACKED STRING NPS INTO INTEGER NS$1 


SO NSS ="? Fine Loe | TO LEN (NPS): NI® = STROCASC(MIDS(NFS+L,>1)}~32) 
82 IF LEN(NI#)(3 THEN NI$*" O” + RIGHT#(NIS,LEN(NIS}41)¢ GOTO 82 
84 NSS * NS& + AIGHTS(NI$,2): NEXT L: RETURN 


2. PACK INTEGER STRING NS® INTO PACKED STRING NPS: 


400 NFS*°"s FF INTCLEN(NS$)/2)%2 €) LEN(NSS) THEN NSS2CHRS(32) + NOt 
405 FOR L = 1 TO LEN(NSS} STEP 2 

410 NPS = NPS + CHRS(VAL(SI OS (NSS) Ls 2) 2 +392) 

415 NEXT L 

420 RF TURN 


DEMONSTRATION ROUTINE: 


1000 INPUT NS$: GOSUB 400: PRINT“PACKED VERSION IS “NPS 
1010 5NSU8 BO: PRINT“UNPACKIO VERSION FS “NSS 
1020 GOTO 1000 


PACKS NUMBERS OF FORMAT $9999.99 WITHOUT THE DECIMAL POINT: 


480 NS LEFTS(NOS,5) «+ RICHTS#(NDS, 2) 
484 GOSUB 400 
488 RETURN 


8.1.11 Rounding is the process of converting and representing a number in a less 
accurate, but more convenient, form: $10 plus 15% is $11.50; $10.45 plus 15% is 
$12.0175; to two decimal places these are 11.50 and 12,02 respectively. (f have not 
considered the question of relative accuracy here, i.e. accuracy to a certain number 
of significant digits). A good rounding routine may format the number to a known 
length with leading spaces, insert {for example) '.00' after a plain integer. and put in 
a leading zero in the case of numbers less than 1, Poor routines may put the decimal 
point In the wrong place, produce spurious values, or print characters like ‘E', on 
Occasion. Alignment may be difficult, and zeroes not treated as a special case. 


DEF FN P(X) = INT(LOG(ABS(X)+,.001) /LOG(10}) 


is intended to calculate the number of places before the decimal point; but there may 
be very occasional errors in the calculations of the logarithms. This expression: 


DEF FR R(X) © INT{100°Z + .5)/200 


rounds X to the nearest 2 decimal placea: adding .5 has the effect of converting a 
number with decimal component greater than .5 into the next highest number on INT. 
This, on PRINT X, given the umuai 1.3 (not 1,30) for 1.3, and 1 (not 1.00) for 1, 
The following more comprehensive routine In intended to round and format numb- 
ete an suggested above, Apart from intermediate variables, the routine uses L to store 
the number to be rounded, RQ (‘rounding quantity’) as a mengure of accuracy, and 
L2 to determine the type of rounding. RQ=106, for example, rounda to 2 decimal places, 
end RQ=t000 to 3. When RQ=100, L2=.005 rounds to the nearest; L220 rounds down; 
and L22.995 rounds up. 


92 LaInT(LeRQoL2)/8Q: JSS=<STAS(L): J5$=K1D9( 83, 2) 

93 JLaLEN(J5$): IF JL>2 THEN IF MID9(J8$,JL-2,1})="," GOTO oF 

94 IF JL>1 THEN IF MIDS(I8S,JL~1,1)0°." THEN JE$aJ8$+"'0": GOTO 96 
O6 J99aJ69+",00" 

96 IF LEFTS(J59,1)="." THEM JA$e"0"+J89 

G7 IPF LEN(IS9)<11 THEN FOR J=LEN(J8$) TO 10: J8$=" “+J89: WERT 
00 RETURN 


Line 92 computes & rovaded string, without » leading space, 

Line 03 Sranches on numbers liks 123,46, 0990,00, 1,23, and .67, 

Line 94 adda & zero to numbera like .B, 122.4, and 90999.9. 

Line 05 converts lotagers to 2 dec. pt. form, e.g, 1234 inta 1234,00, 

Line # adda a leading zero to nuabers like .8, .t2. 

Line 07 edds leading apacea up to a predetermined teagth (il characters here). 
The routine is intandad for positive nuabers > OL. 
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BASIC rounding routines always have a restdual uncertainty about them, because the 
effects of rounding by the calculation routines aren't certain, Chapter §'s PRINT 
USING avoids this difficulty, since it edits the number before output; it is also faster. 
Whenever a rounding routine is to be used, uniess it haa been previously tested, it is 
good practice to write a teat routine to generate numbers to be rounded; either at 
random or in @ sequence. It ls usually impossible to test each individual value. 


€.1.12 RAM data storage has two forma: data may be poked and peeked in some fixed 
part of RAM, typically near the top, or it may be processed by arrays in the normal 
wey, but differ from normal file-handiing in being loaded and saved directly from RAM. 
The first method is useful in association with machine-code: a set of names, key numb- 
ers or indexes can be searched in RAM virtually instantaneoualy, cutting down on disk 
or tape use. The second approach also cuts down on input/ output, and, provided 
that the whole of a batch of data fits RAM, can lead to very efficient processing; for 
example, @ 10K program can coexist with (say) 10000 integers stored in 20K of arrays, 
and both the program and data could be loaded from tape, providing economical pro- 
cessing of quite a large amount of data. The technique is fairly tricky. As we saw in 
Chaptor 2, the program starts in RAM at $0400 and is followed by a bdiock containing 
al! the variables, string pointers, and function definitions so far encountered in the 
running of the program; after this comes a block of arrays and string array pointers. 
If we have integer arraya only, and if every variable is set up already, the position 
of the integer arrays is known, so that they can be saved and reloaded freely. Pro- 
grams using this method will have a isyout of this sort: 


Set (or LOAD) pointers to the correct positions for variables and arrays 
LOAD stored arrays of data 

Menu 

Menu option to save stored data to diak/ tape 


The first time round, with no variables in memory and no data yet on disk, a starting 
up procedure is necessary. This involves (a) entering all the variables in direct mode 
in optinum sequence, e.g. J=0:KK=0:IN$="". (b) Dimensioning all arrays. (¢) GOTO 
the iine after 'LOAD stored arrays of data’. The menu will be displayed, and all the 
variables are in place. The program must be STOPped to peek the pointers needed to 
gave and to reload. If the program la edited, this proceaa will have to be repeated, 
since the position of the data varies with the program length. 
Section 4.1.17 has an example of thia method in use. 


8.1.13 Searchin is necessary whenever a file structure provides no way of caicui~ 
ating the position of a record, Chapter 6 has @ long section on disk files, which looks 
at this problem, With CBM disks, 'reiative files’ (accessed by record number) or dir- 
ect access flles (which must be specially written} enable a record to be found very 
repidiy; sequential fies of any length are much slower. But often the record number 
of a relative file may not be known, or may be teas convenient than (say } entering 4 
name or phone number and welting for the corresponding record to be read. Chapter 
@ explaine how such fifea may be subdivided, so the searching process la uccelerated. 
We may diatingulsh between searches in RAM and those which reud data from 
diak, In the first type, machine-code searches are 40 fnat that the data need not be 
ordered or arranged In any way, It In fast enough, normality, ta scan from the start 
to the finlsh, without elaboration. Section @.7 han a fairly long example, Including both 
BASIC and 4 machine-code subroutine, However, when searching from dink, thia may 
be too alow, Am we saw in Chapter 3, under these circumstances a rearch which con- 
verges on the sought value Is usual. The ‘binary chop' In (he dDest-known, and is casy 
to program. (The 'Flbonacch acarch’ is (rater, but less eanily programmed), [t requires 
that its data be in sorted order, This diagram shows how the convergence tnken place: 


ire Rumen IW aequence: [19 54 8[@ 7 6 0 1O[ii 12 19 14 is] ie 17 14 19 30 
NUMBER OF SEARCHES TAKEN: | 4 J 4 5B 2 Aa 3 4 8 3 4 34 5 “a 463 48 
using the algorithm on the next page, and applying it to 26 Items of data. We can cal- 
Guiate the average number of searchue uned by the plnary chop, by amount of data: 
Nuunen OF Items OF bata. | 86] 160] 200 [ 5% [1990[ 2000! 4000| 9000 | 

AVERAGE NUMBER OF SEARCHES: e{[7fa] of 0 ff it { t2 












| 
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x Input and validate item to be searched for (say, E$ = key item}. 

Ni and 82 set to current low and bigh record ousbers 
y Row INT((N1+N2) /2} :REM CALCULATE NEW MID-POINT 
Read the appropriate field of record 00, R; say RY 
IF A$=K$ GOTO » ;REN FOUND IT? 
IP Nl>=N2 THEM PRINT “RECORD NOT ON FILE": GOTO 5: REM NON-ELISTENT 
IF R$>E$ THEN N2-K-1: GOTO ¢ ;REM BEVISE UPPER LIMIT DOWN 
Wi=R+1: GOTO DREM REVISE LOWER LIWIT UP 
z Continue procesaing the record 


This schematic program of the binary chop search ia, I hope, self-explanatory. Nland 
NZ converge, sandwiching the correct value of R between them. Note that records 
needn't be disk-based; they could as easily be a sorted array in RAM, in which case 
the teat line would read If R$(A}aK$ GOTO z. Try out this technique before implem- 
enting a large system, generating test-data with a program, and timing the result. It 
may be too alow, depending on the disk system and size of file. 


4.1.18 Sorting is an important operation in commercial data processing. (COBOL has 
@ SORT verb). Chapter 5 has a collection of routines, mostly in BASIC, with notes. 
The first example, the ‘tournament’ sort, is unlike ail the others in computing individ- 
ual reguits singly, so that resuits can be printed continually, before all the values 
are ordered, Most sorts wait until the entire batch of data has been ordered, and 
this can be irritating to wait for and slightly worrying, as the machine may appear to 
do nothing for tong periods. The'bubble' sort has achieved fame through being very 
slow. It operates by checking neighbouring values in the array, interchanging those 
which are out of sequence, and repeating this process until the sort is guaranteed, or 
until sny pass takes place without a transposition, depending on the algorithm. That 
in Chapter 5 (section 5.3} has @ test in line 620 which uses a 'finished' flag, The sort 
ls assumed to be in ascending order, and after every pasa another value is positioned 
at its correct value at the ‘top’ of the heap, unless, with a partly-sorted set of data, 
many items are simultaneously sorted. To illustrate the idea, seven figures in the left- 
hand column are shown sorted (in five passes) in the right-hand column. 
Starting at the bottom of the set of data, each 
ftem is compared with its immediate neighbour 
and interchanged if it is out of sequence. The 
process is repeated to a distance up the data 
which depends on the previous number of 
passes; the underlined digit represents the top 
limit In each pass. With n items of data, a 
maximum of n + {n-1) + (n-2) + ... pasaes Is 
required, making about jn’ in ail. On this basis it {a often said that the bubble sort 
takes time proportional to the square of the number of itema to be sorted. However, 
the correct time is very sensitive to partial ordering of the data. The graph at the 
end of SORT shows that new itema, added to an already sorted array, then bubble 
sorted together, is very faat: in fact, under these circumstances, the bubble sort is 
one of the fastest possible, since it does tittle more thun check that each item is corr- 
ectly related to its neighbour, which ls neceauary In any sorting system. The machine- 
code sort operates on atring arrays, changing the pointers where appropriate, and 
using the identical comparison to that of BASIC, for conaistency. It does not sort the 
teroth element. which can therefore be used aa 4 ttle or reminder. If new itema ara 
to be sorted in, keep a number of null or blank elements at the start of the array, 
As the diagram Utustrates, high vatuen {o.@. 6} can else quickly from the bottom, but 
low values (c.g. 1) are alow in descending. Note finatly that tha machine-code can be 
made to sort from the second, third, ..., characters of the sirlng, rather than the 
first, by changing $F In SOJ2K (UASIC 1), or S$7TFRG (BASIC>1) to O (aecend), | 
(third),... A demonstration HASIC routine Is provided with the machine-code, OF the 
other sorta, the Shell-Metzner and Quicksort are well-knawn; the former performs many 
small bubbta sorts on fonglitudinal subsets of the data; the latter compares data with @ 
‘pivot value’, putting the result inte ona or other ‘stuck’ depending on tha Fequle, tt 
May run out of spuce; if so, dimension the array In linn 40 with a larger value. The 
‘scatter’ sort Is an attempt to mimic human sorting: @ subaldlary erray Ls used, inte 
which dota is Ment roughly sorted, on some a priori basis, for oxampis with the As at 
the boginning, Za at the and, and others in between. Then this array in sorted thor- 
oughly, fta uae of RAM [Is too great to permit the mathed to be vary useful on micron, 
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1.15 String handling. CBM BASIC has three closely related string functions, LEFTS, 
MID$, and RIGHTS, each of which extracts a substring from a string, Chapter 5 has 
examples of the use of each function, and an additional functlon INSTRING$, which 
helps illustrate machine-code string handling. Strings can be represented by variables 
or literela (e.g. X$ or "X¥Z"}, and also by the type-conversion functions CHR$ and 
STRS$. Substrings can be concatenated (=chained) together with the binary operator 
tet and in fact any conceivable rearrangement of strings is possible with * and the 
LEFT$, MID$, and RIGHT commands. In many cases, MIDS alone can be used. Note, 
however, that a string's fength cannot exceed 255 bytes, because of the storage method 
used by BASIC. Typical string processing includes the following: 

(1) The use of extended, composite strings. The components need not be the 
same length, but for ease of programming this is usual. 

x9e"eySundayabyaondaypWlussdayWednesdaywThuredayhyNFridayWSaturday” 

print widd(x$, (4-1) *9+1,9) 
Each substring is 9 bytes long (é represents one space éharacter), because the long- 
est component ia "Wednesday". The second expression prints a substring of length 9 
corresponding to the d'th day's name, where d=1 to 7. 

(il) Padding a string with leading or trailing spaces, so that alignment is auto- 
matic on printing out. The obvious way is to add individual spaces: 

POR J=LEN(S$) TO 19: S$e""+S$: NEXT :REM PADS STRINGS OF LENGTH <20 TO 20 
A quicker and more elegant way (which aiso uses less RAM, and is therefore better 
with BASIC<4) is to add the entire substring in a single chunk: 

S$ = LEFTS ("WHEE NESE, 20-LEN(S$}) + S$: REM PADS STRING TO LENGTH 20 

(iii) Scanning a string for certain alphanumerics. In such activities as checking 
& response for accuracy in foreign-language {or English!) teaching, and playing hang- 
man, a FOR ... NEXT loop can examine the string. Let's consider hangman, the word- 
matching game, where W§ is the target word, L$ a guessed letter, which, if it exista 
within W$, appears in the display D$. Typically, WS will be selected by some such 
routine as this: RESTORE: FOR J=1 TO RND(1}#201; REAO W$: NEXT: REM ASSUMES 200 WORDS 
Then D$ is generated with: OS$=LEPT$("-+--<----------------- ",LENCW$)). This gives a 
string of hyphens of the same length as the target word. We now put: D9="y"+D$+"H", 
which is a slight subtiety, enabling us te use only gingie-line processing, without 
having to take account of special cases when the first or last letter has been selected. 
Now, for each letter L$, 

FOR Jwl TO LEN(W3) 

I? LS=4ID9(W$,J,1) THEN GOSUB x: PRINT "(HOME]D$ : REM ASSUMES DISPLAY AT TOP 

REXT 
WS la scanned from beginning to end; if @ match ie found, the string D$ ls revised and 
printed over its previous value. If a letter occurs several times in W$ the procesa re- 
peats, but ia fast enough for the process not to be visible. The subroutine which up- 
dates DS has to insert L$ within D$ at the correct position defined by variable J: 

X DS&=LEFTS(D$,3) + L$ + RIGHT$(D$,LEK(D$)~J~1): BETURN 

liv) Note on BASIC 4: A rare bug may occur when concstenating more than two 

strings, and when fewer than $300 bytes of RAM are free; the string Is corrupted. 


8.1.16 Validation is the process of checking that data is of the correct type, without 
necessarily guaranteeing the actual value. A date $9/19/42 is invalld, bue tf lt la accept: 
ed may cuuse processing errors, and so will be rejected by most systems. The date 
3/8/82 is valld, but may not be correct. Similarly, ‘20' may be an acceptable eniry for 
8 aum of money, but ‘twenty' may not. 

The aimpler forms of validation repeat the request for data In the event of an 
incorrect entry: 

100 INPUT "DISK DRIVE NUWBER"; DS TREK D$ WILL ACCEPT ANYTHING 

110 D=VAL(OS}: LF Dov INT(D) OR D<O GR Dt GUTO 107 : REM INTEGER GO OR 1 ONLY. 
More sophieticated checking muy include error mesaagen (sce 4.1.6) and soft-coding to 
enable scceptable ontrics ta be modified. This batch of eubruutinos hes tests for four 
variabtos, and was uned with a crashproofed [NPUT routine: 


500 1¢ Jabery" or Jaton? then cefurn 

303 okeOiamt=" fo ar No only*® iqnaub 800: return 

510 al b-PABUDt FGlee Tyas?) Por Il to dental$)r1f Jadomicttnl$,$,1) then retuca 
313 newts ohedicnt="1e pales code": qpub800sraturn 

520 nlbe*Oe125"1 tor Jet ta Jentnisdi if Jabemidsinlt,t,1) thee J3e01 ceturn 
323 next) ches ents" ln VAT code": qoqubING! return 

50 It Veegsks hi and ntcdjeti<219) of ae fabseS2 then return 

$33 oheGr ate ia Farelgn code" qoeub8Od: return 
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8.1.17 Arrays (subscripted variables} provide a powerful extension to the usual sys~ 
tem 


simple variables, and ere weil worth mastering for any serious application. The 
principle is to provide a whole series of strings or numbers with a single name, using & 
subscript to distinguish the separate elements. Chapter 5 (see DIM) has infarmation on 
the use of arrays; Chapter 2 explains their storage methods and the pointers which 
keep track of the data. Arrays of numbers, subject to their own rules of addition, sub- 
traction and multiplication, are called ‘matrices’: see Chapter 16 on this, We can think 
of arrays as belonging to one of two classes: ‘one dimensional' and ‘multi-dimensional'. 
The jatter are conceptually more difficult, 50 it makes sense to start with the flrat type:- 


One-dimensional arrays are variables with a single subscript, which may take any value 
from 0 to the dimension of the array in DIM. (If no DIM statement was used, 4 default 
value of 10 1s assigned). Unless an item is specifically assigned a value, it will be 
stored as 0 (numeral) or the nuil qharacter (string array). The array can be visualised 
as a set of consecutively-numbered pigeon-holes, which are filled with a data-item, num- 
erie, integer, or string, by the usual methods of assignment. 

10 IMPUT N: DIM A$(N): FOR J=0 TO N; INPUT A$(J}: NEXT 
inputs the size of the array. then a series of elements to fill it, and can be regarded 
as the array version of INPUT. Similarly the stored results can be output by 

20 FOR J=<O TO N: PRINT AS(J): NEXT 
A typical application of these arrays is the /ook-up table. For example, an array might 
hold opcodes for machine-code: A$(0)="BRK", A$(1}="QRA", and so on, Then there is 
a simple relationship between a peeked vaiue of a location (say, P) and the string AS(P). 
A numeric array could hold the values of the locations of the start of each line on the 
ecreen; DIM L(24) could hold each value from 32768 up. Then the location of the ninth 
character along linge fifteen is L(15)+9. A fifty-two element array might hold all the 
cards in a pack. As mentioned in Chapter 5, the zeroth element can be reserved for 
special purposes, typically for averages or totals. Other uses include the storage of 
values for sorting. The sorts in Chapter 5 all operate on string arrays, which could 
consist of a key (name, catalogue number, reference) followed by 4 relative-file record 
number. An array variable is slower to process than a simple variable, because of the 
processing overhead associated with its subscript. Nevertheless, access is faster than 
some calculations and function evaluations, so look-up tables are sometimes used to speed 
Up programs which contain repetitive calculations on a limited range of arguments. For 
instance, it may be worthwhile to set up a tadle holding present values of money over a 
humber of years, or of square roota from 1 to 100, 

Arraya are useful in games and problems of the board-game or rectangular grid 
type, and we can use this topic as a bridge to multi-dimensional arrays. ingenious 
applications of single-dimension arraya where more dimensions appear appropriate include 
the '8 queens’ problem, where the object is to arrange 8 chess queens on a chessboard 
6o that none attacks any other. An array of only 8 numbers can represent the board; 
tach value must be different, and from 1- § to denote the posltion of that columa’s 
r basil Diagonals are tested by 4 difference method which the diagram illustrates, the 

rat example passing all tests and the second having two attacking queon pairs: 

— 

Another Ingenious algorithm Is that for assessing card strengths in five-card poker: the 
hand ig sorted, and the four consecutive differences evaluated. Of these, there are only 
three of importance: 9,1, and any other value, corresponding respectively to pairs (or 
threes or fours), straighta, and othera. The 34 (=81) possible vaiues cun be assessed 
by an arruy. Chess games are usually stored as an @ by 8 array, pieces being rep- 
resented by a positive or negative number (representing colour) of value related to 
the Importance of the piece. 


Multi-dimensional arrays have more than one subscript; the maximum la 295. It is al- 
wayn possible, though Inconvenient, to simulate such arrayn by partitioning single-dim- 
enalon arrays, so there are BASICs which permit only one nubscript. A nimple two-dim- 
@naionn) cxumple shows how the contents of the array dimensioned by DIM ASCL,7) 


Might b x 
ight be stored; i 3d 
"oN" 
“NEGATIVE "Coup" [vorr’ ("SMALL 


So that INPUT AS(0.d) had taken in LARGE from the keyboard, ar been assigned 
program, and PRINT AS{1,7) prinia the word "ILL", Note that an areny wilh np dimen- 
siona uauaily requires 7 nested loops lo input or output all ite date. 
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These arrays are valuable for storing data for busineas reports, as the example shows. 
The schematic BASIC routine demonstrates the logic which was used to generate the 
reports (which are incomplete here, for reasons of apace restriction). It should be self- 
explanatory. The only subtle paint is the use of an additional code of each type; this is 
an overflow or ‘waatebasket', into which unrecognised items are put. [mn each case the 
contents of this extra, non-existent code should be zero. For example, if a sales code 
had somehow been recorded as "%", J would take the value 15 on leaving line 100. 
FOR ALL RECORDS: READ SALES CODE S$, ORIGIN CODR 0%, AGE CODE A (1-8), VALUE V 
100 FOR J=1 TO 14: IF S$<>MIDS("ABCDEFGJEMPTVX", 5,1) THEN NEXT 
110 BACI,A) = SA(J,A} + ¥ 
220 FOR Jel TO 10: IF O$<>MID$("BCFGHOPQSU",J,1) THEN NEXT 
130 O(S) = O(3) + ¥: O(f}=009) + ¥ 
NEXT 
FOR Jal TO 15: FOR X21 TO 9: SA(J,0)=5A(J,0) + SACJ,E): NEXT: NEXT 
At the end of this process, array SA() holds values by saies code and age code, and 
O() holds the same vaiues by origin code. Totals are held tn the zero elements. 


TOTALS BY SALLS CODE AND ASE CODE 


SMES OWE: A 10343,60 SALES COCE: & HS275.73 SALES CODE: C 38916,30) SMES ONDE: C T9042 
Aga Codo: | 8152.35 Ano Codu: | 40720,77 Aga Coca: t 2872149 Age Coda: 1 507.24 
Age Coda: 2 1256.00 fujo Cade: 2 3128.44 Ago Cote: 2 3295,03 Age Code: 2 152.08 
Age Coda: 3 YW?19 Aja Code: 3 541.57 fia ove: 3 3925,52 Aga Sada; 3 19,10 
Aga Goda: ¢ 136,49 Am Como; 4 365.60 9 Ap Cote: 4 Gh2,46 Ata Cadar ¢ 0.60 
Age Cote: 3 wWo.4e Aya Cots 5 ADOD,UT Aq Cade: $ 1191,06 Aq: Code: § 9.00 
Age Cade; 6 30,49 Ago Code: 6 79452 Ann Coto: 6 94,75 Age Coda: & 0,00 
Age Coder 7 0,00 Ago Gove: ? 0,09 Age Coda: T 9.09 Aqs Code: 7 0,06 
Age Code: Fi 0.00 Ago Coda: 9 0.90 Ann Cote: 8 0,90 Ag Code: & 9.00 
Agn Coda; 9 9,00 Age Code: 9 0.00 Age Comu: 9 0.00 Age Coda: 9 ¢.40 

SALES CODE: € 0.00 SMES COME: F 203849.51 SALES CODE: G $523,860 SALES MOE: J 1a237 68 

Core: 1 0,0c Ago Code: 1 15037,31 Ais Cade: | 1597.80 Age Coda; 1 W505,3% 
Age Coda: 2 0,00 Aga Coda: 2 = 3302.80 © Ago Cro: 2 21.00 Age Coda; 2 $252.12 


SUMPURIES AY SALES CODE, ORIGIN CODE & ACE COOE 


SMES QOOEr A 10343,00 OFAN COLE: 3 §S7."1 ME COME: 1 49536,99 
SALES CODE: @ 3$275,71 ORIGHH CODE: ¢ 223,06 WE COME: 2 19006,55 
SALES Cope, © 916,11 CREGIN GONE: F 2327 49 WE OO; 3 8253,29 
SALES COCK: O 718.42 OKIGI4 CONE: 5 0,00 ME OM: 4 1892.56 
SALES OME: E 0,00 QRIGIN CONE: H 0,0 AGE MOVE: 5 S473,5h 
SMES COOT: F 20185,5¢ ORIGIN COM? 9 P95, 17 ACE TNE: Bb 317.5) 
SALES QOOE: & bt 3.AQ DRIGIN COURS P 56296, 15 AGE COME; fF 0,00 
SALES (ONE: J 182 37,68 CRIGIt COMES 9 239,90 AME OVE: 48 ¢,o0 
SALES CODE: K (73,40 CAIGH MONE: § V36t6417 ME CINE: 7 9.99 
SALFS COME: 4 16313,55 ONGIAN Mh. U OStq ta ME MONE: 0.40 
SALES CONE: P 346.59 TIGTH Cone a,01 

SALES COE: T 0.00 

SAPS ONE: ¥ 0.90 

SALES COE: Xx TALL 

SALES COLL: 0,08 

TATA, RY SALES COME: 122481,93 TOTAL AY GRISI Cit, 12248193 TOTAL BY ADE COOK: 17748) 94 


Two-dimensional arrays may be used to store quite large quantitles of data (about 32K 
less the space occupied by BASIC) very efficiently. t[nteger arraya, which store numb- 
ers from -32768 to 32767 In only 2 bytes, are parilcutarly efficient. They can be saved 
and relouded en bloc to disk, providing rapid access to a lot of data with little dink 
drive use. To understand the appronch, read the next few paragrupha carefully. 

The example we'll consider in a garment inventory system. Its volumes of data 
are: 50 cloth types. identified by a four-digit number, 

Bach cloth Is available in 1 to 12 colourd; the average is aduut 4. 

Each cloth/ colour combination haa i to 8 styles of garment; that Js, a cloth in 
blue may be made Into only one type of Jackat; the asme cioth in brown may be mode 
into two other designs. 

Each garment im produced in wix nizea. 

At each level of complexity. detalles about the cloth or tha clothes are stored; for 
#xample the cloth width 1* recorded for every cloth type, and, at » more datailad levei, 
the quantity in stuck of every alze of anch gurment Is required. 

We can store the data In arraya like this: 
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CASO, 5) M4(200, 3) $4800, 2) SZ4( 9800) 





CL(0,0)= Total number of 
cloths entered 

Ch(n,0}= Choth number 

Cu(n,1)= No. of colours 

h(a, 2)" Delivery date 

CKh(n,3)e Cloth width 

Chi{n,4)= Cumulative no. 
ef colours 


M&(n,0)= Colour cades 
M&(n,1)= Leogth atored $%(n,0)* Telephones 
N&in,2)= Na. of atyles orders 
ME$(n,3}= Cumulative no. S%(n,1})= Style code inventory+ 
of styles S%£(n,2)= Cumulative sone other 
no. of sizas data 


arrays occu 16160 bytes (including the array overheads. See Chap-. 
ny rhe pickets, SOW ihe. way In which one array is dependent on the earlier 
array. The details, once set up, are difficult to alter, because ail the subsequent , 
details are stored immediately after, leaving no room for manoeuvre. €4(0,0) cura A 
holds 3, showing that only three cloths’ data has been keyed in so far. When the nex 
cloth is entered, the fourth row of C%() will fill, 1- 12 rows of M3Q) will depend = 
this, and a maximum of 96 rows In S%(} may be filled in turn. Finally, $24) has from 
1 to 576 elements filled. The cumulative frequency pointers (which are not strictly ce 
necessary} make this scheme fairly easy to implement. However, BASIC propre paler 
store data like this are amongst the most difficult to decipher of any BASIC, the p 
lems increasing with the number of arrays. Whether this is undesirable depends ie 
one’s point of view. Some short extracts from programs show the type of program to 
x pect: 
ALCUMRC(CECNH1,4) + M = 17,4) + ED,0) * P 
aze(eu(s + KE ~ i,1) + 0) = 8ZR(SECT + K-11) 4+ U) + 8 
PRINT M&(CE(N-1,4) + M ,1) ; REM PRINTS AVAILABLE STOCE 


SZ%{n)= 


: REM TELEPHONE ORDERS 
: REM UPDATE STOCK POSN 


Multl-dimensional arrays with more than two dimensions 

are not used much, probably because of the difficulty of 
visualizing the data's storage pattern within ita arrays. 
The diagram (right) Ulustrates a three-dimensionat array, 
set up by the statement DIM X(25.20,3). Since zero ele- 
ments are aliowed, the array's ‘plgeanholes’ occupy 16 by 
21 by 4 locations, Assuming a conventional order or rows, 
then columns, then depth, leada to the diagram, In which 
for instance X(0,0,9) is the top-left element In the 2-dir- 
ansionst array on top of the heap, and X({1,2,3) occupies 
row 1 and column 2 of the array at the bottom of the heap. 
Four-dimensfonal arrsys can be pictured as several stacks 
of three-dimenalon ucraya arranged slde-by-alde, After 
this, depiction becomes progresslvaly more complicated. 
The maximum number of dimenslons ia 255 (sea Chapter 2). 
In practice, shurtage of RAM will make this figure, of anything like it, imposnibie. 
Section 2.3 of Chapter 2 explains the calculations necaseary to determine the total 
Number of bytes taken up in RAM by any array. 
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4.2 Debugging BASIC programs 

This section tists common faults in BASIC programming. While such a list cannot hope to 
be exhaustive, it should help in pinpointing errors. 


Peculiarities of BASIC. These include a few bugs. 

ASC of a null character doesn't evaluate as 0, but crashes. 

CLOSE doesn't properly close an [EEE file without PRINT# to the file. 

DATA statements may give trouble if new DATA statements are inserted before them. 

FOR ... NEXT occasionally behaves oddly: see Chapter 5 on this. 

FRE may be slow in BAS{[Csland 2. See for example Chapter 2. 

INPUT crashes on Return; also input from a file prints no warning message if extra 

data (e.g. separated by commas) has been read in. 

LEFT$, RIGHTS may crash if the numeric part of the argument is 0. 

PRINT attempts to print anything it is given; a stray '.' appears as @, for instance. 

.S saves machine code, omitting the final byte; so add 1 to the end address. 

STR$ introduces a ieuding space into positive numbers. 

TAB and SPC have some quirks carried over from CBM BASIC's ancestors. 
Numerais are hetd and formatted to a certain degree of accuracy; see Chapter 13. 
Strings have a maximum length of 255; attempts to exceed this give ?string too long. 
Some mathematical functions will not accept certain values without error. 

CBM disks: see the end of Chapter 6 for a summary of possible bugs. 

Differences between BASIC ROMs are outlined in Chapter 2 and explained eisewhere In 
detail. BASIC 4 disk commands, and SYS calls to ROM, are nearly always 
incompatible between BASICs. 


Syntax errors are usually fairly self-explanatory. These cases may be difficult: 
(i) Included keywords. Misprints are particularly easy with logical constructions, 
because these are largely alphabetic. If A=B OF C=D reads IF A=BO=0 for example. 
i) FOUT OF MEMORY has diverse causes:~- 
i. Too many tevels of brackets, especially within loops and subroutines. 
li, Absence of POP causing RETURNs to duild up on the stack. See Chapter 
5. Example: IF ASC(1N$)=27 THEN POP:GOTO MENU correctly aborts input. 
iti. Insufficient RAM, especially with large arrays. 
iv. Can occur when start and end of program pointers are altered. 


tneorrect processing, without Syntax error Indication is often caused by one of these:- 
(t) Variable name repeated by mistake. See Chapter 2's variable name fist. 
(H) Variable value changed in error. Typically fom L214 TO 10: GOSUB 100: NEXT 
(iii) Wrong meaning of a statement. Very common with logical expressions, 
(iv) Subroutines may be poorly structured, so program flow drops through. 
(v) Omlssion of 'FN‘ wilh cause 4 function to de read ag an array, Example: PRINT FN 
DEEK(X) mistyped as PRINT DEEK(X) ia interpreted PRINT DE(X). 


Errors caused by assuming » software setup appear when a program ia re-run but not 
preceded by a setting-up program; examples include failure to specify the screen char- 
acter get, failure to change memory pointers, failure to send controt commands to the 
printer, and sometimes the use of LOAD within a program. Operators accustomed to a 
rigoroua input validation may not adapt to the occasional use of INPUT, 


Systematic, recurrent errors are usually caused by faults in the logic of programs: 

(1) The zeroth or last entries in buffers may be omitted or misplaced. 

(il) Graphica or data-storage POKEs' may change atrings, vartables, BASIC, or 
machine-code. 

(ii) Keyboard entries at tha wrong time or of the wrong sort may corrupt data, for 
example where an ESCopa key allowa exit from any routine back ty the menu, 

(iv} Tha logic of (say) ao merga may be faulty in special canes. Identifying those 
may be difficult, requiring a puinetaking dry run through tha code, 


Hardware problems can be dutreted hy teat programa. But during the course of run- 
ning programs, trivial hardware problems may be ovarlooked; 
tl) Shift-lock on causes the screen appenrance of Inputs to be odd, and may cause 
apparently valld key etttrica to be rojected. 
(U1) A printer may Jack paper or ribbon, or not be oniine, and so fall to function, 
it may be wrongly act, 
(iU) Dlak drives may be off or disconnected. 


fo SPS eter 


ord 
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CHAPTER 5: ALPHABETIC REFERENCE TO BASIC KEYWORDS 





This chapter lists all CBM BASIC keywords with explanations, examples, notes, and 
details of their operation at machine-code level, it should be useful to the learner, and 
also provide a convenient source of reference to experienced programmers who wish to 
check up on programming queries of the sort which inevitably arise in the course of 
writing programs. I have occasionally drawn attention to differences between CBM 
BASIC and other dialects of BASIC. The format of the explanations is roughly consist- 
ent for each keyword, which appears in bold type at the top of the page. Normal type 
indicates 'keywords' which sre not present in CBM BASIC. but which can be written 
for it or adapted from other sources, or obtained in software form or as plug-in 
EPROMs. BASIC 4's specificatly disk oriented keywords are listed in Chapter 7. 


Note on BASIC operators. 


When a string expression or arithmetic expression is evaluated, the result depends on 
{a) the priority assigned to each operater, and 

(b) the presence of parentheses. 

Parentheses, in either string or arithmetic calculations, have the effect of ensuring 
that the entire expression within parentheses is evaluated as 4 unit. In the absence 
of parentheses, priority is assigned to operators in this order, starting high: 


1 Power 

+-  Unary plus and minus 

* 7 Multhply and divide 

+~ Binary plus and minus 

< = > Comparisons - fess than, equal to, greater than 
NOT Logical NOT - unary operator 

AND Logical ANO - binary operator 

CR Logical OR ~ binary operator 


The arithmetic operators are relatively familiar and straightforward. Note the high 
priority of unary plus and minus; the point of this is illustrated by expressions like: 


at-4¢3 and $e*-+43 and ~1234 * - 2345, 


which otherwise are meaningless. CBM BASIC evaiuates a ‘true' statement ag -1, and 
8 'fatee' statement as 0. These are not standard between computers; Apple for example 
has true = 1, and other differences in interpretation. CBM comparisons are straight- 
forward with numerats, but tess so with strings, which are compared ag fur ae the 
shorter string. So "I" as a string ia < "10", but aiso "5S" la > "449", CHM BASIC's 
Jogke! operators use # 16-bit, 2-byte system; this means that 'truc', which ls printed 
aa -t, ls held as #FFFF. The maximum range of arguments for logical expressions is 
therefore -32768 to 32767, PRINT NOT 32768, for example, gives an crror. Because 
vel flips the 16 bita of the argument, X plua NOT X always add to -1, so NOT 10 is 
It ls important to reatlse that the /ower priority operators have the largest 
Sphere of Influence, an it might be called. Ordinary arithmetic illusatrutes this in many 
ways: 2x ¢ 1 ia immediately seen to be twice x, plue |, With the less common logical 
ea comparison operators, this is rather easier to forget. See for example note (3) 
oO AND, 


4 
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ABS 


BASIC arithmetic function 


PURPOSE: Computes the absolute vatue of the arithmetic expression in parentheses 
fottowing ABS. In other words, ABS makes a negative Qumber or expression 
positive. This function has some applications in programming with numbers; 
kt Is not a major feature of BASIC. 


Syntax: ABS(arithmatic expression), A string expression, or incorrect arithmetic 
expression, will generate one of a number of errors, including syntax, type 
mismatch, and division by zero errors, An expression which, when evaluated, 
is too large, causes an overftow error, Like alt functions, ABS can appear 
on the sight of an assignment statement, within a PRINT statement, and as 
part of « logical expression, for example after IF. 


Modes: Both direct and program modes are valid. 


Examples: IF ABS{QTY} > 10000 THEN PRINT "*"; REM PRINT WARNING ASTERISE 
K = +-12.5 ¢ .5: PRINT ABS(X)} : REM PRINTS 12 
4000 IF ABS(X ~ X1}< 15-6 THEN PRINT "FINISHED": END 
2000 Z% = ABS(10*SIN(X)): REM Z%=INTEGRAL PART OF ABSOLUTE VALUE 
10220 IF ABS(AZ%-BX%)<4 AND ABS(AY%-BY%)<4 GOTO 10200: REM FETCH BETTER START POSNS 


The first example prints an asterisk if variable QT exceeds 10000,or if QT 
ig negative with magnitude larger than 10000, such 4s - 25342, 3, 


The third example shows how to test for approximate equality; this may be 
very useful when allowing for rounding errors and when performing iterative 
calculations which converge ta some correct value. [n this example, the value 
fa accepted if the maximum error is IE-6 (.000001), Typically, the more exact 
the precision, the longer such a program will take to run. 


Fourthly, 2% in line 2000 takes integer values 0-10 only, in a pattern resembling 
a rectified sine curve. The very last line is taken from a game in which each 
player has a ‘worm’ to control on the screen; this line ensures that the 
atarting positions of player A and player B, which are generated by the RND 
function, are not too close together. 


Abbreviated entry: «8 


Token: $B6 (182) ptend 
: expression in parentheses is evaluated and checked, and t va 

Laat thhe fede point accumulator #1. ABS operates only on the sign byte 
of thla accumulator. in fact ALS does less work than any other function. 
The sign byte (location $63, or $B5 in BASICL) is shifted right, so that the 
negative (high) dit is not set. It does thia whether or not the byte was neg 
ative. Ao far aa further calculations are concerned, the number is positive, 
There ls no logs of accuracy in this converalan inslde the accumulator, ae 
as with all numerical expressions, there may be a loss so far ag the initla 
evaluation procesa is concerned. That is, ABS(-123456789012) and 
ABS(123456789012) ore identical, Dut don't retaln all the figures of the 


original arguments. 
ROM antry points: — 


BASIC 1: $DOZA ($4108) 
BASIC 2: $OB64 (56164) 
BASIC 4: SCORE (62422) 





we a 


er 
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AND 


BASIC binary logical operator 


§: BASIC keywords 


PURPOSE: Calculates the logical AND of two expressions which are first converted 
into 2-byte integers. The result is itself a 2-byte integer. If the expressions 
were logical, the vatues 0 (‘false’) and -1 (‘true’) obtain, so the truth-value 
of a multiple condition can be found. 


Syntax: Arithmetic or logical expression AND arithmetic or logical expression. 
Roth expressions must be integers within the range -32768 to 32767, or 
floating point numbers which round down to within this range. Logical 
expressions invariably fall within this range. since they take values of -1 
or 0 only. Out of range values, string expressions, and syntax errors in 
either of the two expressions will cause an appropriate error message to be 
printed to the screen. 


Modes: Direct and program modes are both valid. 


Exampies: PRINT 380 aND 75 
100 IF D%>0 AND D4¢100 THEN PRINT "WITHIN RANGE 1-98" 
6260 OK = -1 AND Y¥>79 AND ¥<90 AND M>O AND M<13 
146 IF Jl=46 AND JD=0 THEN JD~i+LEN(JS$) 


The first example is a straightforward 16-bit AND between two numerals. 
The values and their bit equivalents are 380 (=400000001 91111100) and 
75 ¢=%00000000 01001011), so 360 AND 75 is evaluated by CBM BASIC as 
$00000000 0100100 or 72. 


The second exampie shows AND used in a composite test; both parts of the 
test must be true to print the message. 


The third example is a simptified part of a date validation subroutine. The 
object is to check that the decade is the 909 and the month within the usual 
renge. OK is set to ‘true’, ANDed with four separate tests, each of which 
must be true if OK is to remain true. 


Finally, another example of a composite test: this tine, from a very long 
input routine, accepta decimal numbers which it build into a string JS$. 

Jl is the ASCII value of the last key pressed; JD Is the position of the 
decimal point, or zero if no decimal point has yet been input. The example 
tests for the truth of two conditions: if the decimal point (ie full stop. with 
ASCII value 46) has been typed at the keyboard, and also this key is an 
acceptable one, then the decimal point's position in J5$ Is flxed, 


Notes: [1] The truth table for AND is:- 


ANDIT F AND|1 0 Where 1='true’ or ‘bit set on', 
Q='false’ or ‘bit set off, 
F\F F O10 @ 


Note that when stored as 2-byte signed integers, false =0 =$0000, whereas 
true 2-1 <$FFFF, (To convert $FFFF into Its positive equivalent, flip the 
bits and add 1. Thla method gives $0000+1, so SFFFF is -1). This is why 
AND with a false expression is always false, while AND with a true ex- - 
Pression leaves the value unaltered. It is also the reason that NOT-! la 0 
and vice versa, 


(2) Hlerarechy. BASIC order coplen FORTRAN end ALGOL. NOT then AND 
then finally OR have the lowest priority of all the operators. AND la 
therefore processed loxt in muny cases. 


[3] Comman bugs: Jegical expressions are quilts tricky; errors are compaer- 
atively casy to overtook. Hecause of this four examples of typical wrang 
atstemonts follow: 


[1] DB = Do Dit + 36O*¥ + IBTCY/E) = CINTCY 494407) AND M>2 


This ia teken fram a routine to fInd the weekday. The day, month and year 
are combined mathematically into a parameter taking anly the values 0-4. 
In the exumple, the final expressions are Intended to aubtract | should the 
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year be a leap year and the month be March to December. But because of 
the low priority given to AND, if M is i or 2, the entire expression eval- 
uates as 0. Everything after '=' and before AND is calculated, but this re- 
sult is then ANDed with 0. This shows the power of a low priority command 
which could be compared - perhaps a little fancifully - to a recessive gene. 
The correct version hus the joint expression enclosed in another set of 
parentheses, 


[44] 1” INTC(Y/4)*4=Y AMD M>2 TREN DEw1 


Logical operators have relatively few syntactical requirements and so, if mis- 
typed, are difficult for the translator to distinguish from variables. The line 


when run will not, as might be expected, cause a ’SYNTAX ERROR message. 


Instead it is interpreted like this: 
IP INT(¥/4)*4=YA>2 THEN DE=1 
and its run-time behavicur will depend on whether YA exists. 
(141) LF PEEK(C+1) AND PEEE(C+2)=0 THEN END: REM END OF PROGRAN REACHED 


Failure to fully specify ali the conditions is a source of bugs: the example 
is supposed to find two zero bytes at the end of a BASIC program stored in 
RAM. What is needed is this: 

IF PEEK(C+2}20 AND PEEE(C+2)=0 THEN END 
or: 

IF PEEK(C+L) + PEEK(C+2)*0 THEN END 


The incorrect version will stop whenever PEEK({C+2) is zero and PEEK(C+t) 
i non-zero, 


({iv] IF J<1 AND §>8 THEN 

Never happens! 
Abbreviated entry: aN 
Taken: $AF (175} 


Operation: Binary operators are evatuated with the first argument in floating point 
accumulator #1, and the second in accumulator #2, AND uses exactly the same 
routine aa OR, except that on entry a test location is loaded with zero. (OR 
loadsa it with #$FF)}. Thia is the only difference between these routines. Each 
accumulator in turn is converted into a 2-byte integer, and the low and high 
bytes are processed separately. Using ‘TEST’ to refer to the byte in the 
test tocatlon, the routine computes this function: 

TEST EOR ( (TEST EOR A) AND (TEST EOR B)}. 
When TEST ia #$00, EOR TEST has no effect, so 


A AND B = ( A AND B) 
A OR B.1 NOT( NOT A AND NOT B) 


All ROMs process this Inatructlon In the same way. 
ROM entry points: 


BASIC 1: $CEDS (52953) 
BASIC 2; SCRCB (52939) 
BASIC 4: $CO6u (49289) 


Santee tat 
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APPEND 


System command unavailable directly in CBM BASIC 


PURPOSE: Links two programs end-to-end into a single program. This can be 
very helpful in adding standard subroutines or BASIC utilities such as 
erose-referencers onto a BASIC program. 


NOTE: APPEND in the sense used here applies ta SASIC programs only, not 
files of data, and may be run on any CBM machine, irrespective of whether 
or not it is equipped with disks. 


Versions: Appending one program onto another requires that the linenumbers do 
not overlap; If they do, a program with lines 10 20 30 and 50, say, which 
has another program with 40 50 and 60 appended to it will appear as one 
program linenumbered 10 20 30 50 40 50 G0. If the routines aren't too tong, 
they can be listed on the screen and incorporated into the main program by 
loading it, homing the cursor, ana entering the lines remaining on the 

* sereen. Longer routines would require a boring, but reliable, process of 
repeatediy loading the routine to be appended, loading the program, adding 
new lines, and saving the result so far. This process gives a MERGE, not 
an append; a merge is often potentially more use than an append, but is 
harder to inplement. 


Amongst the versions that have been written are several for tape: Jim Russo 
and Henry Chow's Merger’ (Pet User Notes, Nov-Dec ‘78) and Roy Bus- 
diecker ‘Universal Tape Append’ (Compute! Mar '8i}) are two. They use 

the same method, namely loading the second tape to start at the end address 
of the first program. From the users's point of view this is fairly nice and 
easy; att you do is press ‘play' twice. The routine to be appended must be 
at the start of another tape, or at a known position. Between these two 
versions’ publishing dates, a lot has happened, and much of Busdiecker's 
article is concerned with variations between ROMs. Disk versions are less 
sophisticated usually, because the header is more difficult to get at. For 
example CPUCN 2#5 has a 30-line program which reads a program, writes 

ft as data, reads the nexts program, and writes it to the same file. See 
Chapter 6 for details. 


The version below uses a different principle, and will append programa 
from different sources and recorded on different machines. The prograin 
to be appended - |.e. added onto the end - is loaded first. Then a SYS 
command moves the entire program up memory into the high end of RAM, 
as indicated oy the pointer; so protected machine-code ls untouched. Then 
the maln program is loaded, and a second SYS command shifts the first 
program back te connect with the aecond. The program also rechaings the 
BASIC lines, ao that the link addressea are correct. I have included an 
OUT OF MEMORY indication if the programa together are too large. The 
USR locations 1 and 2 store temporary pointers, 50 If you're using USR, 
these will need resctting. 


Examples. 

[1] Load the append program, then run It, so that caseette buffar #1 
holds the machine-code. Now enter SYS 634, This moves the append 
program itself into hlgh memory. 


Type NEW and enter 100 PRINT “HELLO”. 


This short program {a held in the ordinary BASIC part of RAM . 
atarilng at $0401. 


SY8 673 will move APPEND down again from ita poaltion higher in 
RAM. [t will be positioned correctly and chained, ao that on LISTing 
youl ace ling 100 at the atart of the program, which runa normally, 
apart from briefly printing "HELLO". 


Don't RUN « program between the two SYS commands, as strings may 
corrupt the part of memory atoring the program to be appended. 
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{2] Load any program; type SYS 634, (Both SYS commands can be 
used repeatedly without reloading). Now load any other program 
(or the same one again!) and enter SYS 673. The new composite 
program should be correctly linked and should run as one pro~ 
gram. If you type SYS 634 agaln, the new program wiil move 
up memory and a further program can be inserted at the start. 


Notes: [1] ROMs. The BASIC loader is set up for the upgrade ROM (BASIC 2), 
BASIC 4@ shares pointers with BASIC 2, and is therefore an identical 
routine, except for two absolute addresses. The data statements finish 
with two jumps ($4C = 76 decimal}; one rechains the appended programs, 
the other prints the out-of-memory message when an append is impossible. 
BASIC 4 requires IMP $84B6 and JMP $B3CD in place of the upgrade ROM 


routines. So BO DATA .... 76,182,180,76,205,179 is correct for BASIC 4. 
eran 1 (Old ROM') needs pointers from 40-53 decimal to be changed to 
135. 


{2] Cassette Buffers. With BASIC 4 in mind, I've written the routine to 
load into cassette buffer #1, which is untouched by BASIC 4’s disk hand- 
ling. If loading is to be done from cassette #1, this buffer will of course 
be overwritten, so the machine-code must be loaded elsewhere, the obvious 
place being buffer #2. The code relocates, so substitute 826-864 for 
$34-672, and 965-934 for 673-742. 


BASIC 2 APPEND ROUTINE:~ 


0 PORE 59466, 12: PRINT "[CLEAR]$$$$$$" :REM UNDERLINE (SHIFT+$} TIDIES TITLE 
1 ae [REVS]APPEND*: PRINT *(DOWN] MACHINE CODE IS NOW LOADED INTO SYS 634 AND SYS 
2 PRINT “[DOWN) LOAD THE PROGRAM TO HE APPENDED; ENTER (REVS)]SYS 634(RVSO] 7} 
3 PRINT “TO STORE IT HIGH UP IN MEMORY. 
PRINT "[OCOWN)JLOAD THE MAIN PROGRAM AND ENTER (REVS]SYS 673(RVSO),TO 7) 
PRINT "MOVE THE PIRST PROGRAM DOWN AGAIN, ONTO THE END OF THE PRESENT ONE 
6 PRINT “[DOWNJLINES ARE AUTOMATICALLY LINKED. ‘* 
10 DATA 165,53,133,2, 165,52, 33,1, 160,0, 165, 1,208.2, 199,2, 194, 1,177, 42 
DATA 145,1,165,42,205,2, 198,43, 198,42, 208,234, 165,43, 201,4, 208,228, 96 
POR L = 634 TO 672: READ M: POKE L,M: NEXT: REM SYS 634 MOVES PROGRAM 
50 DATA 160, 0,56, 165, t,229, 42, 165,2, 229,43, 144,54, 165,42 oT 
60 DATA 268,2,190,43, 196,42, 177,42, 200,244,56,165,42,233,1,176,2 
70 OATA 198,43, 133,42,177,1, 145,42,230,42,208,2, 230,431,230, 1,208,2,230,2 
89 DATA 165,53,197,2, 208, 234, 165,52, 197, 1,208,228, 76,66, 196, 76,85, 195 
wee L = 67) TO 742: READ M: FOKE L,Ms NEXT: REM SYS 673 APPENDS PROGRAM 


Top of ZAM pointer 98000 
PROGRAMZ GOO 


PROGRAMS 000| | PROGRAMS OO [vDU__] 


Temporary pointer 


lo PROGRAMA ho | PROGRAZ oO] 


out of mem, test 


o Frock procane of dd 
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ASC 


BASIC arithmetic function of string argument 


PURPOSE; Computes the Commodore ASCII value of the initial character of a 
string expression, ASC is essential when testing individual characters, for 
example screen formatting characters from the keyboard, and generally 
whenever the numerical equivalent of an ASCII character is more easily 
handled than the character itself. 


Syntax: ASC(atring expression). The string expression can be any valid express- 
ion of literals, string functions and the '+’ concatenator, with the single 
exception of the null character "". Any string whose length is 0 élicits an 
ALLEGAL QUANTITY ERROR message; in practice the null charocter as 
defined by "" is the only easy way to generate such a string. The CBM 
ASCII value as returned by ASC can take any value from 0-255; a table in 
the appendices shows the relationships between characters and their ASCH 
values. Note that ASC(X$)=0 when X$=CHR5(0); this is not the same as "" 
in Commodore's BASIC. 


Modes: Direct and program modes are both valid. 


Examples: 160 GRT J1$: IF Jigs" GOTO 160 
163 J1*ASC(J1L$): IF J1=13 THEN : REN PROCESS CARRIAGE RETURN 


164 IF Jix20 THEN: REM PROCESS DELETE KEY 


This incomplete program extract shows how keyboard entries can be process- 
ed: line 160 GETs « key, avoiding the 7illegal quantity trap by testing for 
the null character. When 4 key has been entered, it is converted to its ASCII 
value for processing. Complete validation of keyboard entries in BASIC can 
be carried out in this manner, with the exception of the STOP key only. 


1340 FOR L=1 TO 6: POKKE 799+L, ASC(MID$(TEST$,L)): NEXT 


This example shows the method to move a string into RAM: the string TES 
of length 6 ig POKEd into focations 800 to 905, for use in a machine-code 
comparison routine, from BASIC, in six separate pokes. 


92000 IF PEEE(QQ}=ASC("*") THEN ERA$a” © SET” 
PRINT ASC(MID$(S$,L)) - 192 : REM CONVERTS UPPER CASE A-Z TO 1-26 


Finally, the third example shows how readability can be improved by using 
the ASCH function itself, rather than its value - 42 in the case of "*". 
The fourth example prints the Lth letter of string $$ as a number from 1 to 
26, so if S%="HELLO" and L=2, the value 5 appears. This type of routine is 
useful whan computing check digits, enciphering data, and 80 on. 


Notes: (1) The converse function to ASC is CHR$. PRINT ASC(CHR&(N)) prints 
N. STR$ Is not the converse: STR%$(42) Is not an asterisk, but * 42". 


Abbreviated entry: a3 


Token: $C6 (198) 


Operation: After the function's string expression has been evaluated, it is set up 
In RAM with its 3 parameters (length and 2 dyte pointer) on the stack. ASC 
recovers these parameters. it tests the length, and if this la zero exits 
with "llegel quantity. This is surety a bug; there la no problem in making 
the value 0, However, now the accumulator ia loaded from memory, using the 
string's pointers, ao whatever the length of the string, its initial is fotehed. 
This value Is the ASCII value: there is no conversion carricd out on the byte. 
h wtandard ROM routine turne it Lnto the floating point equivalent in accum- 
ulator #1. 

All ROMa process this function in this way. 


ROM entry points: 


BASIC 1: $0663 (64683) 
BASIC 2: SDA85 (54685) 
PABIC 4: BCSC1. (61193) 
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ATN 


BASIC arithmetic function 


PURPOSE: Calculates in rodlans the principal value of the arctangent of the argu~ 
ment; this can be any arithmetic expression irrespective of sign. Thediagram 
iustretes the relationship between two sides of a right-angled triangte, and 
the angle calculated by ATN. 


NOTE: This function has no connection with ATN on the lEEE bus, which is 
the ‘attention’ line, 


Syntax: ATN(arithmetic expression). The expression must be syntactically correct 
and within the range acceptable to the floating point logic (41.7 E38 approx), 


Modes: Direct and program modes are both valid. 


Examples: 1100 ALPHA «© ~ATN (¥YV/ZV9; BETA = -ATN(KV/ZV}: 
2130 LET R=ATN( (E2-E1}/(N2-N1) ): REM COMPUTE BEARING AND DISTANCE 


Both examples, as might be expected, are related to trigonometry; one is 
from a perspective plotting program, the other from a two dimensional pro- 
gram for surveyors in which coordinates easting and northing are input. 
In ¢ach case the assigned variable, ALPHA, BETA, and R, takes the value 
of an angle in radians, which therefore is in the range -pi/2 to +pi/2. 


Notes: (1) The diagram shows the connection between X and ATN(X), for those who 
ere unused to geometry; a right angled triangle is a convenient standard to 
demonstrate geometrical ratios, but has no particular significance beyond its 
ease of use. ’ 


{2) See the appendix on trig. functions for general solutions. 

{3] To convert radians to degrees, multiply by 180/pt. This changes the 
range of values of ATN from -pi/2 - pi/2 to -90° - 909. 

{4] In some cases, ATN(X)} is a useful transformation to apply, aince it 
condenses almost the entire number range into a finite set from about -1.57 
to +1,57. 


Abbreviated antry: aT 
Token: $C) (193) 


Operation: The actual evaluation uses a 12-constant series summation. The argument 


{after validation} is converted into the range 0-1: if negative, the sign is 
stored for later recovery, but the calculation ls cacried out on the absolute 
value, And if the argument is greater than 1, the reciprocal is used in the 
series, and thé result subtracted from pi/2 (90°), 


All ROMa process this instruction in the same way. That ie to say, the logic 
ip identical, even though the entry polats, absolute addresgea, and (with 
BASIC 1) zero page locations vary. : 


ROM entry points: 


‘ 


BASIC 1: $2048 (57418) 
BASIC 2: $EO8C (57484) 
BASIC 4: $D329C (54060) 





a 


Seeaniles 
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AUTO 


BASIC system command not available directly In CBM BASIC 
PURPOSE: Utility to generate linenumbers when entering BASIC program lines. 


Versions: Typically these generate linenumbers starting at 100 and incrementing 
in steps of 10. The usual implementation {9 a BASIC routine to print numb- 
ers and to input an entire tine when return is pressed, using the keyboard 
buffer to accept two carriage return characters. One of these causes the 
line to be incorporated into the program; the next runs the program again. 
This is algo a favourite machine-code command on EPROMs from 'Tooikit’ through 
to ‘Power’. 


The following routine has these features: 

[1] Optional flashing cursor; omit the POKE in 60010 if this is not needed. 
[2] Check for premature return, so that a linenumber is not wasted, 

{3] Lines up to length 80 are accepted 

(4] Press STOP to stop. 


60000 INPUT "AUTO: ENTER START, INCREMENT"; S,I 

@0010 PRINT “[CLE] [DOWN] [DOWN] (DOWN)"; S;: POKE 187,0 

60020 GET A$: IF A$="" GOTO 60020 

80030 PRINT A$;: IF ASC(A$)<>13 THEN 60020 

$0040 P = PEEK(32889 + LEN(STR$(5))): IF P=32 OR P=160 GOTO 40010 
60050 PRINT “S=" S+I ":r=" I ':GOTO 60010[HOKE}" 

60060 PCEE 158,2: POKE 623,13: POKE 624,13 

60070 END 


Note that line 60040 checks the focation just after the linenumber; if it finds 
either a space or a shift-space. clearly nothing has been entered in the line 
eo far. The routine therefore prints the same linenumber again. The value 
32889 fs 32768 + 121, which is appropriate to 40-column screens. With the 
8032 this must be replaced by 32768+241 = 33069. 


BASIC 1 PETa have the keyboard buffer(and much more) differentty arrang- 
ed. Line 60010 requires POKE 548,0 and line 60060 becomes 
60060 POKE 525,2; POKE 527,13: POKE 528,13 


ES ee Te NL NINE 7 Fe AC se Ee EN A a aN 
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CHR$ 


BASIC string function of numeric argument 


PURPOSE: Converts any numeric expression In the range 0-255 inte @ string with 
fength 1 consisting of the CBM ASCII equivalent character. This is the only 
convenient method to print and manipulate special characters like carriage 
return and ", which are CHR$(13) and CHR$(34) respectively. 


Syntax: CHRS(numeric expression). The expression in parentheses must evaluate 
to 0-255. If the number is non-integral, it will be rounded down, and this 
rounded value must be in the correct range. So CHR#{-.01), CHRS$(500) and 
CHR$({X%$)} cause error messages. 


Modes: Direct and program modes are both vatid. 


Examples: A$ = CHRS$(34) + CHAS(18) + "NAME" + CHR$(146) + CHRS (34) 
N8$ = CBR$(160) + NSS 
PRINT CHR$(7} 
3300 PRINT#4, CER$ (27) "EB08'CHRS(27) "LOG" 


The four examples above illustrate the use of this function to construct in- 
dividual characters which are otherwise difficult to deal with. The first puts 
a string within quotation marks, and adds the [RVS} and [RVSOFF) charact- 
ers. The second adds a leading shifted-space to a atring; this is more read- 
able than the alternative NS$ = " “ + NS%. CHR$(7} is the ‘bell', and this 
command will make appropriately equipped CBMs tinkle and printers beep. 
The final example shows a command typical of non-IEEE, non-Commodore 
printers; CHR$(27) is ‘Escape’ and the string sets horizontal and vertical 
spacing on a Qume daisywheel printer. 


PRINT CHRS(34);: FOR J = 1025 TO 1100: PRINT CHAS(PEEK(J}}i: NEXT 
C$=""; FOR J = 1 TO 6; C% = C$ + CHRS$(PEEX(AKT + J)): NEXT 


Conversions of the contents of RAM into strings can be performed in BASIC by 
combining CHR$ with PEEK. The first example, in direct mode, prints a line 
or two of BASIC as it is stored in RAM.(This is not the best method}. The 
second recovers a string which haa been poked into RAM; C$ is built up one 
character at a time until a 6-character long string is formed. 


Notes: {1] CHR$ is the converse function toASC, A particular application of these 
functions is conversion from one character set to another, for instance screen 
dumping to a printer, where the PEEKed value needa a fairty elaborate routine 
to ensure that it PRINTs the way It looks on the VDU. See DUMP. 

[2] CHR$(0) represents a null character, but has length 1. This may result 
in some anomailes; X$=X$*CHR$(9) adds a trailing null character to X$, the 
length of which Is also incremented by 1, but the nulls do not print; so X$'s 
length appears to be longer than X$. Embedded null characters can be insert- 
ed into strings: ¥$="123" + CHR$(0} + "45" prints 12345 but returns VAL 
of 123 and LEN of 6. If sorted, Y$ precedes 123*5, 12344, and so on. Note 
that ""<CHR$(0) Is ‘true’, rather oddly. 


Abbrevisted entry: cH (includes the $)} 


Token: $C7 (193) : 


Operation: First, the contents of the parentheses are found and checked for range 
0-255. Provided thin is correct, a string of length 1 $a set up at the current 
atring pointer ponition, and the single byte value stored in this location. If 
the string le assigned - X$-CifH4( 123} say - this atcing Is permanent, if the 
string is used as an intermediate only, on in PRINT CHR%(123), the pointera 
are not reset and the next atring will overlay the character. 

All ROMs process thin function in thie way. 


ROM entry polnts: 


BASIC 1: @DOC4 (94724) 
BASIC 2; ODSCE (54728) 
BASIC 4: $CBI2 (51234) 


27 SO eg 
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CLOSE 


BASIC input/output command 


PURPOSE: Completes the processing of a file and deletes the file and its details 
from the three file tables. Files opened to the keyboard or the screen are 
deleted {rom the tables with no other action. Cassette files opened for 
reading ere dealt with in the same way. But cassette files which write data 
also write a zero byte to denote end-of-file; and if the secondary address 
was 2, @ tape ‘header’ is also written holding the end-of-tape value of #5. 
1EEE files with secondary address zero - usually, non-CBM hardware - again 
are simply removed from the tables; other IEEE files are sent commands to 
close files, and this function is carried out by the receiving hardware. In 
the case of CBM disks, an end-of-file; indicator is put into the last sector 
of the file, so that the chaining sequence of tracks and sectors for that 
file is complete and up-to-date and terminates correctly. 


Syntax: The syntax is identical to that of CLOSE; however, any parameters 
following the logical fite number are subsequently overwritten by CLOSE, 
so for practical purposes CLOSE arith. expr. is the correct syntax, where 
the expression must evaluate, after rounding down, to t-255. If the file 
does not exist, no error message results. 


Modes: Direct and program modes are both valid. 


Examples: OPEN 4,4: PRINT#4,"HELLO!“: CLOSE 4: REM MESSAGE TO PRINTER 
OPEN 1,1,1, "PILE": PRINT#L, "HELLO!": CLOSE 1: REM WESSAGE TO TAPE 
100 CLOSE 1,2,3,°4": REM SAME EFFECT AS CLOSE t 
1000 PRINT#S,CHR$(13);; CLOSE #: REM BASIC<4 DISK FILE CLOSE 
1100 PRINT#4: CLOSE 4: REM CLOSE PRINTER, WHEN CMD HAS BEEN USED 


CLOSE is « straightforward command, made more complicated than need be 
the case by the behaviour of CMD and PRINT#, The former leaves output 
devicea etill listening, and needs a final PRINT# to unlisten the bus; the 
latter, on CBM disk drives using BASIC<4, prints extra linefeed characters 
(ASCII character 10) after the carriage returns which mark the end of 
adjacent records. BASIC 4 also has the DCLOSE command. 


Notes: [1] RAM Tables. CLOSE deletes three entries from these tables (see OPEN 
for Mustrations) uniesa the entry happens to de the last of the files, by 
overwriting its three parameters by those of the last entry, then reducing 
the number of files open by 1. This of course is designed so that the ten 
fea maximum may be efficlently used. Sometimes, notably after editing a 
program, the number-of-open-files parameter jis set to ¢, leaving the tables 
in RAM. if a file has not deen closed, due to Stap or perhaps a syntax 
error, it may stilt be possible to close it by poking In the number of open 
files (or 16) and closing the file in direct mode. The location Is 174 (610 
in BASIC 1). Alternatively, OPENIS,8,15: CLOSE 15 fs suggested in a manual. 


{2) Disk Fleas. Piles opened for read need not be closed except to make 
space for more filles. CBM disk files opened for write must siways be CLOSED 
correctly. Otherwise, the track/sector pointer in the final sector will point 
to ¢ usable area on the disk; sooner or iater two files wilf become Intertocked 
and the dato on one corrupted, See COLLECT for more on this subject. 


Abbreviated entry: clO 
Token: $A0 (160) 


Operation: Parumetera sre fetched by the identical routine used by OPEN. The 
logical fle ts looked for, and, if found, ite parameters aro taken fram tha 
tables ere overwrite any other values. The davice number determinos which 
branch js now tsken; caasettes, screen, and keyboard aro procenscd as 
described above: [EEE devicas aino call a 'Claar Channel’ ROM routine, 

ROM entry points: CLOSE ja a ‘kernol' command. Its addrese la S¥FC3, it calle: 
BASIC 1: $F2C@ (82162) LOA file no, then: §P2CD (83157) CLOAEs. 

BASIC 2; OFdA@ (42121) “ OFZAER (82126) * 
BASIC 4: $F2D0 (63173) , $F2E2 (62178) ig 
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CLR 


BASIC command 


PURPOSE: Appears to erase all BASIC variables currently in memory, leaving the 
BASIC program, if there is one, unchanged. Any machine code routines in 
RAM are left unaltered. 


Syntax: CLR. CLR has no parameters, It may be followed by spaces, but must 
be followed by a colon or and end-of-line zero byte. (Some versions of BASIC 
use & parameter with CLEAR to allocate specially reserved RAM: this cannot 
be done directly with Commodore's CLR). 


Modes: Direct and program modes are both valid. 


Examples: CLR 
50000 CLR: 7°VARIABLES ALL ERASED”: REM ALL RESULTS SO FAR ARE LOST. 
10 POKY $2.0: POKE 53,48: CLR: REM TOP OF MEWORY IS NOW $3000 
10 POKX 134,128: PORE 135,48: CLR: REN OLD ROM: TOP OF RAM=$3800 


This command operates by moving pointers about; it does not erase variabies 
in the sense of, say, putting null cheracters in all the locations which pre- 
viously held data. The first two exemples are straightforward; in direct 
mode, if X perhaps was 1.414 and S$ was "J, Smith", then after CLR both 
variables will return 0 or null, as appropriate to the variable type. And In 
program mode the same effect obtains. Program running is not changed; so 
the program carries on as before, except that its variables, which presum~ 
ably aren't wanted, are cleared. Also references to subroutines and loops 
are lost. For a complete description of this command, read the detailed ex~- 
planations which follow. However, it is not necessary to fully understand its 
operation. The final two examples, which are alternative program lines, one 
for BASIC 1, show how CLA can be exploited for useful purposes, given an 
understanding of its modus operandi. A pair of zero-page pointers hold the 
location of top of RAM; this is not set by hardware, but by the machine itself 
on switechon. If new, low values are poked in the machine acts as though its 
RAM storage had been reduced; strings which normally fill RAM to its limit 
now limit themselves to the new value. In this way, free RAM is made avail- 
able to the programmer for machine code routines and general storage. CLR 
ensures consistency between ali the pointers. 


Notes: [1] Simple variables (Integers, strings. floating-point variables and function 
definitions) and arrays (integer, atring. and floating-point) are deleted.In 
additlan the DATA pointer is RESTOREd and the stack pointer reset, losing 
alt FOR .. NEXT and GOSUB .. RETURN references. SFFE7 in ROM ia called 
to abort input/output activity: flies are aborted and the screen and keyboard 
are reatored to primacy. 


12] There is no-easy way to erase strings only, for example, or just integ- 
ers. [t is possible to erase arrays; their polnters are held differently, ag is 
neceasary to avoid ambiguity. After CLR, variable and array pointers are not 
dlatingulshable, so recovering the lost vaiues is difficult. 


(3] Aa with NEW, CLR generates anomalous error mearnages if a muchine-code 
program has been loaded or the BASIC pointers are abnormuaily set for sone 
other resson. Poking values for the stert and end of BASIC, then CLRing, 
ia one poasible cure. 


Abbreviated entry: cL Token: $8C (156) 


Operation: The ‘limit of RAM’ pointer, ns we've seen, Ia stored in the ‘bottom of 
strings’ pointer; thin menns that new stringa wil be stored in the top of mem- 
ory, overwriting the old onea. The ‘end of BASIC! pointer is stored in the 
tend of varinbles’ and ‘end of arrays’ pointers, Thin Insea both variables 
and atring pointers, When the atack In rect, the tep two values ara rotaln- 
ed, ao RTS continues the program running at the samo place. In additlon ta 
the changes ilated In note [1] o few Mage are renet, 


ROM entry polnts: BABICL:SC77O (51056) BASICI: $0577 {BOSHi) BARICE: $UGES (445674) 





nee 
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CMD 


BASIC output command 


PURPOSE: CMD combines two entirely distinct functions. (i} !t prepares an output 
device, typically a printer, to receive subsequent PRIMTed data until the 
device is unilstened. (ii) 1¢ then prints whatever string follows CMD to the 
printer or other device. In essence it @lows a program with many PRINT 
statements, which would normally appear on the screen, to he diverted to 
some ather output device, 


5: BASIC keywords 


Syntax: CMD arithmetic expression: 
CMD arithmetic expression, printable expression including . andfor ; 
The arithmetic expression must evaluate to 1-255. A logical file number of 
zero is disallowed. The comma separator, for example in CMD5,"HELLO", 
appears with INPUT# too, but not with PRINT. This is because PRINT 26 
ig syntactically correct, but CMD 5 25 is ambiguous. 


Modes: Direct and program modes are both valid. 


Examples: Assume OPEN 5,4 has opened a file to a printer. (OPEN 4,4 may well be 
used in practice: I've put 5 purely to make clear which parameter is which. 


cup $ evitches further output to printer, Then prints crif. 
CMD 5,; * Without crif. 
CuD 3, “HELLO” = & prints “HELLO” 
PRNT=$: CMD PRNT is syotectically ralid, 


Notes: [1] If we compare PRINT#5,"HELLO” with CMD5."HELLO” it is clear that 
these instructions are rather similar; however, the puzzling feature of the 
commands is that PRINT#5,; which unlistens the device does exactly the 
opposite of CMD5,; which causes it to listen. This confusing aspect of CMD 
ia the resuit of its combining two disparate instructions. 


{2] Problems: CMD often gives rise to minor bugs. 


{1] OPEN 4,4: CMD 4: INPUT "NAME"; NS ; REM "NAME" IS PRINTED 
{14] GET turne off CMD; only one iine appears on the printer: 
10 OFEM 4,4: CMD 4,; 
20 PRINT “LINE” REM PRINT LINE REPEATEDLY... 
30 GET X$: IF X$="'" GOTO 20 ; AEM IF NO KEY IA PRESSED? 
40 PRINT#4,;: CLOSE 4: END 
[1441] Commodore printers (not others) somehow tend to make CMD fail 
to operate. GOSUB for example haa this etflect. 


{3] To summarise, CMD seems to be, in the US phrase, a kludge to enabie 
a program full of print statements to be easily diverted from the screen to 
some other device. [t is canier than replacing all PRINTa with PRINTS. 
When developing a new program, PRINT# le likely to be a better choice: it 
lends itaelf better to CLOSE and will not lose Its effect erraticaiiy. Also 
Commodore (cf. their printers) seem to support PRINT# in preference. 


Abbraviated entry: cM 
Token: $90 (157) 


Operation: Tho parameter following the CMD token is checked. It must evaluate 
to 1-255. The dovice number corresponding to thin fiie number Is looked up 
in a tuble of up to 10 values, and the output device set. ?PILF NOT OPEN 
or 7DEVICE NOT PRESENT errocu may greet the user whila thia is being 
attempted. The syntax Is checked after CMD's parameter. Either an end-of- 
statement (colon or naw ilno) or commy followed by printable expression |a 
accepted. Finoilt, the PRINT routine in ROM la entered. 


ROM antry points: 


BABIC 1: $CO8S (51089) 
BASIC 2: MATL (51601) 
BASIC 4: SRARE (47758) 
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§: BASIC keywords 


CONT : 


BASIC command j 


PURPOSE: Resumes SASIC program running after encountering STOP or ENO in 
the program, or after the STOP key had been pressed, or after a nuil input 
crash on INPUT. In this way not only can breakpoints be put into BASIC, 
but @ program can be stopped and restarted at any point, (Well ... nearly 
any point. The STOP key will abort files, so that its message and READY 
will appear on the VDU; in some cases therefore CONT does not completely 
resume operation}. 


Syntax: CONT. No other parameters; may be followed by spaces, but must be 
followed by a statement terminator - a colon or end of line. 


Modes: Direct mode only. (In program mode CONT goes into an infinite loop which 
continually jumps to itself). 


Notes: [1] As a BASIC program runs, & record is kept of current and previous 
Unenumbers, and a pointer is kept which indicates where the next state- 
ment is. All this is part of the overhead which helps to make translators 
alower than compilers. It also makes useful commands like CONT possible. 
The HELP command, implemented on some toolkits to point to the error in 
a@ line which has caused a syntax error, uses the linenumber and pointer; 
the routine cannot be in BASIC, which would change the pointer, but must 
LIST a single line in machine-code and then calculate where in the L15Ted 
line the error was located. 


{2} While the program is stopped, any of its variables may be examined by 
PRINTing; their values can also be changed in direct mode. With CBM BASIC 
new Lines can’t be added if CONT is to work. A °CAN'T CONTINUE ERROR 
Ig also caused after CLR or NEW or if exit from the program was by way of 
a syntax error. In such cases, GOTO a convenient linenumber may serve 
the same purpose. 


[3] The principal locations are: ($3A) holds 'previous Uinenumber', 

($38) holda the pointer into BASIC. 
The high byte of ($38) is made zero if exit was by syntax error; by POKE- 
ing these locations, CONT can be made to work, and jump to anywhere in 
BASIC, although there‘s little practical value in doing this. 


Abbreviated entry: cO 
Token: $9A (154) 


Operation: First the syntax is checked. Then the pointer Into BASIC used by 
CONT (not the same as CHRGET) is tested for high byte zero, which ts # 
gtandard test for a syntax error exit. Obviously &@ valid pointer into BASIC 
must be $0400 or greater, so the zero byte never lends to ambiguity. If @ 
zero byte is found, therefore, the routine branches to print the cun’t cont- 
inue message. Otherwise, and let us hope usually, the routine puts the 
stored previous \Inenumber into the ‘present Ilnenumber’ alot, sets GETCHR 
to the pointer to the next statement, and rungs. 


ROM entry points: 


BASIC 1: $C74S (51013) Unvalidated: $0747 
BABIC 2: $C7EB (51031) " #C78D 
BASIC 4: SB7RE (47085) " $a7FO 
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cos 


BASIC arithmetic function 


5: BASIC keywords 


PURPOSE: Evaluates the cosine of the argument, which is assumed to be in 
radians. The cosine Is a ratio which is constant for an angle; the diagram 
Wlustrates this. 


Syntax: COS(arithmetic expression}. The expression must be syntactically correct 
and within the range acceptable to the floating-point logic (41.7 E38 approx). 


Modes: Direct and program modes are both valid. 


Examples: PRINT COS(1) printe cosine of 1 radian = .34 approx. 
PRINT COS(45 * [P1]/180} prints cosine of 45° = ,707 approx. 
1000 YaRXP(-K*T) © (A*SINCW*T) + BeCOS (W*T}) 
2000 X=ALPHA+SIN (ALPHA): Yo1-N*COS (ALPHA) 


The first examples show COS used in direct mode (sometimes called 'caicul- 
ator mode'!) performing direct calculations. The conversion between degrees 
and radians has to be performed by the user. The second examples are 
typical formulas using trigonometrical functions; the first is the equation 
of a damped sine curve. The second calculates two coordinates, X and Y, 
on a cycloid. 


Notes:{1} The diagrams show the cosine'sa ratio in terms of a right angled triangle 
and the concept of a radian. 'A‘ and 'H' conventionally represent sides ad- | 
jacent to X and hypotenuse (diagonal), respectively. 


r 


A 
COS(X) = A/H 


[Z} Accuracy ia not greatly affected by the size of the angle: this function 
operates by dividing the argument by 2*pi and taking the remainder, 30 
there is no series approximation error related to the size of the argument, 
ot ae error caused by the limited precision to which the argument can 

C . 


(3] See the appendices for the inverse functlon ARCCOS. 
Abbreviated entry: None 
Taken: SBE (190) 


Operation: The argument is evaluated.and the result put into floating-point accum- 
ulator #1. Pi/2 1s added and the routine then drops Into SIN, so COS(X)is 
avaluated as SIN(X + pi/2). 


ROM entry points: 


BASIC 1: SDFGE (37246) 
BASIC 2: $DPD8 (37304) 
BASIC 4: $D282 (83690) 


Angle = 1 radian 
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CRUNCH 


BASIC system command unavailable directty in CBM BASIC - 


PURPOSE: Improves the speed of BASIC execution by deleting as much of the 
program as is considered redundant. 


Versions: Quite a number have been issued; some, in BASIC, are only suitable 
for preparation of a 'fast' version of the program; some machine code 
versions may be used at run-time. The routine is also called ‘compactor’. 
Uncrunch programs, which present each instruction spaced out cn its own 
individual line, are possible too. 


The rationale is that REM statements, spaces, short lines and so on, while 
helpful to an investigator into a program, slow the transiator by wasting 
time jumping past spaces, switching to new lines and so on, and indirectly 
by slowing up GOTOs and GOSUBs, lengthening the program and thus 
causing more garbage collection, and so on. Unfortunately, it must be 
said that such mechanica! ways of speeding up program execution do not 
have a great effect, even with specially constructed programs; their appeal 
is really of the ‘every little bit helps' type. 

Various points of attack are:~ 

(21] Elimination of all REM statements and lines. If they are referenced by 
GOTO or GOSU or THEN the REM statement only may be retained, or, 
better, deleted but with its reference changed to the next line. 

{2} Elimination of all spaces which are not within quotes. (Some BASICs, 
e.g. Apple's, do this anyway). A program modified in this way sometimes 
gives problems; <=T AND U will think it contains the function TAN. 

(3) Elimination of lines by conflating as many together as possible. Lines 
spanning more than 255 bytes are unreliable, however, since pointers for 
DATA for example are single-byte only. Also the program won't LIST. So 
the maximum linetength is usually limited to 250 BASIC characters. Also, 
af course, a line may be referenced, say by GOTO, and therefore not be 
eonflatable with the previous line{s). 

14] Renumbering the program with lines starting at 0 and increment of 1 
makes line references as short as possible: processing ‘GOTO 53° is faster 
than ‘GOTO 12600’ 

{5} Systematic changes of variable names to 1 character nemes only, where 
possible, speeds up variable processing . 

18] Spare semi-cotons can be removed trom PRINT statements. 

{11 Since the program has no spaces, the CHRGET routine may be modified 
to exclude the check for spaces. 

{a} A trace or shadow routine might be able to count the frequencles with 
which variables are used during an actual program run; an initlalisation 
routine could be added to the program to eseign the variables in thelr 
optimum order. 

For further discussion on these polnts, see Chapter 2. 


{9] Where a ‘wedge’ fs {n use, which intercepta the GETCHR routine, 
considerable timcanving is often possible by deleting it with a ahort 6502 
routing, if it im not required at run-time. 


See Chapter 14 for detalla, 


{10} Pinally, the interrupt sequence can be shortened. Sinca the keyboard 
buffer will not work if this is done, itn ume ia flaited to programa which 
perform prolonged procossing without intervention by an operntor, 


Sea Chapter 13 for detalls on this polnt. 
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5: BASIC keywords 


The BASIC routines on this page illustrate the sart of methods by which BASIC 
programs may be compressed, They arc far slower than the machine-code 
equivalents but nevertheless have some interest. The first. longer subroutine, 
to be appended on or near the end of a BASIC program, deletes all spaces not 
within quotes from the program, and deletes all REM statements from lines 
unless the entire line Is a REM statement. [n this case, only REM is left in 
place of the original REM Sine; it is not completely erased, since it may be the 
destination of a GOTO or GOSUB. Note that abbreviated forms of keywords 
appear on the screen; this prevents over-iong lines from overrunning the 
standard 80 character linelength. (Because of the way the listing has been 
printed, the abbreviation of ‘END’ has appeared 'En‘'. This means unshifted 

E followed by shifted N. The same sort of thing is true for the other abbreviat- 
fons, which are, of course, identical to those printed in the BASIC keywords 
reference section}. 


63000 POKE59458,62:A=1025:8=256:GOSUB 63100;GOTO 63003:REM *** AS STARTER 

63002 B=256:A=8*PEEK (826) +PEEK (27 }: A*PEEK{A)+B*PEEX(A+1):GOSUB 63100 

63003 L=PEEK{(A+2)¢B*PEEK(At3}: IF L262999 THEN PRINT* FINISHED": END 

63004 PRINT“ (CLEAR) [DOWN] [DOWN] [DOWN] "L“ [LEFT] *;:O0¢0:REM PRINT LINENUMBER, SET QUOTES 
63006 POR K=A+4 TO A+93: P=PEEK(K): REM NOW LOOP THROUGH LINE 

63008 IP P=0 THEN 63050:REM END OF LINE 

63010 IF Pei4@) AND K<oA+4 THEN PRINT’ (LEFT) ";:GOTO63050:REM DEL 'REM' UNLESS AT S 
63032 [F P=143 THEN PRINT"REM“; :GOTO63050:REM LEAVE 'REM" IF AT START 

63014 If Pwi4 AND Q THEN (90; PRINTCHRS(34);:NEXT: REM ENO OF QUOTES 

63016 IP P=34 AND NOT Q THEN Q=-1:PRINTCHR$(34); :NEXT:REM START OF QUOTES 

63018 IFNOTQANDP> 127ANDP<202 THEN PRINTTS$(P-127};:NEXT:REM PRINT EXPANDED TOKEN 
63020 IF P=32 AND NOT Q THEN NEXT:REM IGNORE SPACE 

63022 PRINTCHRS(P);:NEXT:REM PRINT VARIABLES, INTEGER, $,% ETC 

63050 PRINT: PRINT"GOTO63002":REM PREPARE FOR NEXT LINE 

63052 POKE 826,A/B; POXE 827,A-INT(A/B)*B;POKE 158, 2:POKE623, 13; POXE624, t} 

$3054 PRINT*[UP} [UP] [UP] [UP] (UP) [UP] [UP] "END 

$3100 DATA®** "En" "Fo", “Ne”, "Da", “In”, “INPUT”, "Di", “Re”,LET, "Go",*Ru", “IF","REs® 
$2101 DATA"GOs","REt", REM, "St? ,ON, “wa, "Lo", "Sa%, "Ve", "De", "Po", "Pr7,?, "Co, "Li*® 
$3102 DATA“CL™, "Om", "Sy", "Op", "CLO", "Ge* ,NEW, “Ta”, TO, FN, "Sp", "Th", "No", *STe",+ 
63103 DATA-,*,/,7, “An”, OR, >,*,¢,"5q", INT, "Ab", "Us" "Fr", “Po”, "Sq", “Rn”, LOG, "Ex" 
63104 DATACOS, “SL”, TAN, “At, "Pe", LEN, "STr", "Va", "Ag", "Ch", "LEf™, "Rit, "Mi* 

63108 FOR K=1 TO JES: READ X$:1F XS<¢>"***" THEN NEXT: REM READ OATA UP TO * 

$3110 O1mM T$(75):REM ARRAY FOR TOKENS 

$3112 FOR Kel TO 75: READ T$(X}:NEXT: RETURN: REM FLLLS ARRAY WITH EXPANDED TOKENS 


This second subroutine belongs at the start of BASIC and has the functlon of 
combining several lines into one. The composite Ilne consists of the original 
lines separated by colons. The maximum linelength resulting must not exceed 
251 characters, since the ROM rechaining routine {amongat others) cannot 
then operate property. 

IMPUT "COMBINE LINES";L,U: C=#1028; B=256: ExPEXK(42)+B*PEZEK{43)-4 
LT PEEK (C+2)¢B*PESK(C+3): PRINT LT;: ARM PRINTS LINZNUMBERS 

IF LTcL THEM CePEEK(C)+B*PEERK(C+2): GOTO £; REM FIND LOWER LINE 

TP LT>L THEM PRINT “LINE NOT FOUND"; EXD 

CaC+4: REM START EXAMINING BYTES IN THE PROGRAM LINE 

Q=PEEK(C): IP Q<>0 THEN CeCol:. GOTO 5: AEM FIND END OF LIME ZERO 
LT=PREK(C+3)+B*PZEX(C+#4): PRINT LT;: REM PRINT LINENUMBER 

IF LToU THEN SYS 46262: END: REM RECHAIN, (NOTE®* BASIC 4 VERSION) 
POKE C,A8CC°;}:; FOR J=eC+1 TO RB: POKER J,PEEK(J+4): NEXT: E=E-4:GOTOS 


** BASIC 2: Line 7 containa AY® 60242, but ia otherwise identical. ©. 
“* BASIC 1: Line O hee EoPRER(124)+B*PREK(125)-4. Line 7 uses S¥8 40427. 
And line 8 wust be spread over 2 lines, 6 & 9, because POKE of PEEK fuila. 


Chapter 2 oxpiaina the working of those routines and othera like thom. 


eax e@gveunwy 5d 
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DATA 


BASIC data marker 
PURPOSE: Enables cata of any type, alphabetic, numeric, or ASCII to be stored 
within a program, without being read from disk ar tape or being keyed in. 
The data is retrieved by the READ statement which assigns each item of 
data to a variable in the same order that the data is stored. Originally, 
BASIC accepted data from punched cards, not from keyboards, so READ : 
statements appeared throughout programs in the way [INPUT and GET do t 
now. : 
Syntax; DATA is followed by ASCII characters interpreted like this:- : 
* detimits a literal, which is READ as a singie string t 
, outside of quotes separates one DATA item from the next i 
: outside quotes, or a new line, ends the DATA statement. f 
Other characters are treated as data. Note that the position within a pro- : 
gram of DATA statements is irrelevant, but the order is important. : 


Mode: Program mode only is valid. (The data pointer starts at BASIC, and cannot 
reference data in the input buffer). 


Examples: 100 DATA Al, Aluminum, 24.6", “Cu, Copper, 136.2", "Fe, Lron, 35.1" 
12000 DATA MACHINECODE , 120, 169, 46,132, 96: PRINT “STARTING. .“ 
$0000 DATA 27,14,27,9,22,9,22,9: REM HORIZONTAL 
50010 DATA 3,4,5,9,8,9,9,10 : REM VERTICAL 
$0020 DATA 1,20,2,6,¢,6,5,6 + RRM LENGTHS OF INPUTS 


The first example shows three strings held as data; READ X$ takes in the 
entire string within quotes, so READ X3: PRINT XS repeated three times 
prints each string. The second example shows data with @ special marker; 
a block of DATA beginning in this way can be made relocatable, using a 
loop to read all the data until, in this example, X% say = "MACHINECODE". 
Finally, three lines show how data can be structured. Three sets of eight 
parameters hold details relevant to a screen input format. 


Notes: [I] DATA is used for repetitive work: sometimes there ia no need for DATA 
e.g. PU$="EachPackUnitT ubeReelSet Pair" holds information as a string. The 
commend {3s processed by the same routines that INPUT and GET use, which 
explains the punctuation by “and , and :. Also the variables must be of 
the same iype as the data. Read X$ ig always safe, but READ Y may not 
be. See READ for full explanations of these points. Note also that RESTORE 
seta the pointer to DATA back to start, 6o data ls always rereadable. 


(2] DATA atatements can be forced into a program using the keyboard buff- 

ar to simulate keyboard entry of a line, , 
{3] Buga: (1) DATA ures INPUT's routines, 30 some peculiarities of INPUT 

affect READ. Unshifted leading spaces and some gruphlies are lost. 

(4) Syntax error reported in 4 valid DATA Ine In fact means that there ie 

an error in the READ statement. You'll have to search to find which one. 

(Hi) Unnoticed commas can introduce baffing Lugs. The statement 2 
DATA 21,20,31,20, has 5 dota Items, including a null string. 

(lv) Take cere when introducing ‘more DATA into a progrum which has some 

alroady. READ will impartially trent information Jn the wronw eaequence as a 
though It were correct. Thia can create preblema, especlaily with 6502 code. 

(v) A variable cannot be input: DATA 1,2,3,% trents X as a atring. 


Abbraviated entry: dA Token: $83 (131) 


eta coger 


Operetion: When a dsta statement is found, It is ignored, Just like @ remark 


atatement except that the next atatemant, not the next lino, ie jumped to. 


The routine hunts for a : or zero byle, the Y¥ regiatar holding tha offset; 
this is added to CHRGET's addrass no the affect is to skip the data. 


ROM entry pointe: 
BASIC 1: $C7FO (81184) BASIC a; $COU0 (61200) BASIC 4; $8983 (47235) 


=, 
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§: BASIC keywords 


DBL 


Command unavailable directly in CBM BASIC 


PURPOSE: increases the accuracy of calculations by increasing 
; i pac 
of floating-point numbers. : * ails aol 


Versions: Some BASICs (18M, Tandy) have commands of this type, in whi 
allocated for the storage of floating-point numbers is, for aeuapte. cua. 
Longer numerais are slower to process, but more accurate. Commodore (and 
Apple, which has nearly identical number processing routines) are designed 
around their standard five byte storage system, and it is impossible to extend 
the processing capability of the current routines. (There are rumours that 
BASIC 5 will include BCD arithmetic, enabling great accuracy to be obtained) 
It is certainly possible to reach the point at which numerals are no longer : 
processed accurately. Thus 999 $99 999.1 is printed as 999999999, and any 
values much larger are converted so they appear in scientific notation, There 
is of course an element of spurious ‘accuracy’ in many figures of this magnit- 
ude, Not many measurements are correct to one part in a thousand million. 
There are few routines available, as a result of this, to process long numerais. 
Osborne/Donahue has 25 pages on the subject.* The best approech is to use 
fixed-point numbers; in this way all the difficuities associated with floating- 
point accumulators are abolished. A usable format might be 15 figures before 
and after the decimal point. plus extra space to allow the output to be group- 
ed in sets of three digits separated by commas or spaces. Fifteen figures 
after the decimal may seem excessive; but some calculations, for instance 
overnight interest on bank deposits, need considerable precision. The BASIC 
translater could be programmed to intercept and process (say) AS=AL1S*A2S 
But this would be ambiguous in the case AS$=A1$+A2$. So the best routine is 
ae Me use a ee this: 'A$+B$ or this: SYS 700: A$+BS, and, to 

aving to pee e answe 
paberrlhis cay P r byte by byte, to assign the result to 


‘ce - + a 
uae ne BASIC programa which edd, subtract, and multiply (not divide) 
appeared i y. The relevant chapter ts ‘Making the most of CBM featurea’ which 
he eins ' the eartier edition as ‘Overcoming the limitations of PET BASIC’. 
melas ie ere hee huge: the firmt item gust have an even numbar of char- 
hes Siu aioe zeros may crash the program. To remedy thia, add: 
2180 RETUAR 
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DEF FN 


BASIC command 


PURPOSE: Assigns a numerical functlon, which can be called by FN. The function 
definition has a name (of the usual BASIC type} and a dependent variable. 


Syntax: DEF FN real variable (real variable} = arithmetic expression. The variable 
in brackets is the dependent variable. If the arithmetic expression doeg not 
include it, it's called a ‘dummy variable’, The definition has to fit into one 
line of BASIC. After the function has been defined, it can perform calculations 
on its argument: PRINT FN name (arith. expr.) for instance prints the value 
taken by the function. There may be run time errors if the function cannot 
be evaluated, typically ?DIVISION BY ZERO ERROR. : 


Mode: Program mode oniy; direct mode produces an ILLEGAL DIRECT ERROR. 


Examples: 10 DEF FN DESK(X)=PEER(1) + 256*PEEK(X+1):REM SETS UP FN DE{%) 
100 DEF FN MIN(X)= -(A28)*B - (B>=A)*A = :REM RETURNS SMALLER 
1500 DEP FN ¥(X)oA*X*X + B*X + C :RAM CALCULATE AX? +BX+C 
S27 DEF FN L(QQ)<QQ¢(B=10): REM ALWAYS 0; OR -QQ WHEN B=10 


Line 10 defines DEEK(X) as a double-byte peek. The result is much easier to 
read than a subroutine; PRINT FN DEEK(i) prints the current USR address 
which 1g stored in bytes 1 and 2. If X is negative, or exceeds 65535, the 
program will of course crash, with an error. The second cxample uses X as 
a dummy variable. {n the same way that FRE(0) and FRE(99) return the same 
value, FN MIN(1) and FN MIN(9) take the identical value, which is A lf Ais 
smaller, 8 if B is smaller. Line 1500 is a mathematical function: the example 
is a quadratic expression; it could be a financial calculation, a scientific 
formula, a commercial cost expression. Note that line 1500 includes three 
variables.A, 8B, and C, which are included in the evaluation of the quadratic. 
The function can of course contain constants: 


10 DEF FN Z(Z)=5*(1+TAN(X)), and it can include a function def- 


inition: 15000 DEF FN P{P) = bk + 24(1-P) + 3*{1-P)42 + ... +FN PP(P) 
15005 DEF FN PP(P)= 8*(1-P}07 + 79(1-P)<8: REM 2 LINES POR DEF 


Notes: (1] DEF works by storing a pointer to the expression among the simple 
variables. FN causes the dependent variable to be assigned the value In 
brackets, and then the BASIC code in the program itself ja used to evaluate 
PN. A function can be redefined freely, like any other yariable: DEF FN 
¥(X)sX: DEF FNY(X)=22: In OK. The definition ia stored tike this: 

PTR. TO EAPR. | PTR, TG YAR. 

ASCI1+128| ASCIE LOW KIGH Low HIGH 
The high bits in the name. which are on and off respectively, ensure there 
will not be confusion with other variable types, SO DEF FNX(X>=X4+X$ is valid, 

{2] Buga. b. PN called before the equivalent DEF FN gives 7UNDEF'D FUNC~ 
TION ERROR, becaune it Is unable to flnd, and can't set up, the function. 
ii. An error in the function definition causes *SYNTAX ERROR in the line 
ualng FN, even if the line ls valid. (READ does the same thing). 

. Ha new program is loaded from within an old one, unless it has an 

Identical definitlon In the {dentical place in RAM, any function definitlons 
which existed will no tonger work correctly, and should be redefined. 
{3] Note that the dependent varlable dues not change when a function definitio 
in used. So. In the very first example above, %#100; PRINT PN DEER(1090) leave 
X unchanged, although FN DERK uses XM. The value of X ia in fact temporarily 
stared In the aren reserved for the funeiivn definition Ltaelf, 

Abbreviated entry: dé (fn hus no short form) Tokens: DEP $96 (150), FN $A5(185)} 

Operation: DEF checks FN token, mode, varlatie typea, brackets, and '*’, but not 


the expression, then acts tha name and potniers. FN ham no action adrlrena; 
It Ja searched for during expresaion evajuation and haw Its own ROM routine. 





ROM entry polnts: 
Der: BASIC 1:@D206 (33009) BASIC 2:9028D (53901) BABIC 4: 9C40C (60396) 


rm: HABIC 2:9D9D8 (83074) SBABIC 2:4D2CE (33068) BASIC 4; $COID (49461) 
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DEL 


BASIC command not avaitable in CBM BASIC, 


PURPOSE: DEL deletes BASIC program lines; typical syntax is DEL a - b where 
a and b are finenumbers. This command removes test routines and driver 
routines to clean up @ program when testing is over, or removes particular 
features of a program to leave a core of reusable standard routines. 


NB: DELETE is sometimes a disk command t He; ' i 
sa ik ap oracle ‘a remove o file; ‘SCRATCH! is 


Versions ; In view of the simplicity of programming and usefulness of this command 
it is remarkable how few versions exist, In Microsoft BASIC DEL can only 
be supported in direct mode, because the program shrinks, and the storage 
of variables has to be revised. Validation of DEL a - b is similar to LIST 
and the operation of the routine would be to search for the two lines, then 


memory move the upper part of the program to th 
Bae ene progr e end of the lower part, 


The version below is in BASIC, in the form of a subroutine which sits at 
the end of the program. RUN 61000 inputs the linenumber limits, and the 
coutine proceeds to print on the screen all the linenumbers which the pro- 
gram has detween (and including) the limits. It relies on the well-known 
keyboard buffer trick of putting in carriage returns from the program. 


race Az102$: B=256; INPUT "DELETE FROM,TO";L,U 

10 IF PEEK(A+2)+B*PEER(A+3) ¢ L THEN A=PEEK(A)+B* : 

61020 POKE €28,U-INT(U/B)*8: POKE 829,U/B: pas we Pee ee 
61030 B=256: A=PEEK(826}+B*PEEK (827): U=PEEK(828)+B*PEEK (829) 

61040 IF PEEX(A+2)+B*PEEK(A+3) > U GA PEEK{A)+B*PEEK(A+1)=0 THEN END 

61050 PRINT "[CLR) [DOWN] (DOWN) (DOWN)" PEEK(A+2)+B*PEEK{A+3) : 

‘ PRINT "GOTO 61030": PRINT “(UP][UP](UP}(UP](UP](UP] (UP) 

ea sy 826,A-INT(A/B)*B: PORE 827,A/8: POKE 158,2:POKE 623,29:POKE 624,13 


Comments: 


Asfirat byte of link address; so its Initial value is 10 i 

tos 25, and the pointer to 
the next line, and the fe 
Shares. current linenumber, are stored in locations A/A+l1, 
B=256 ia a convenlent conatant. 


61000 inpute L,U = lower and upper linenumbers 
ainee scana the [ine numbers unt one is found which ia not lesa than L 
20 stores the upper lincnumber in cassette buffer #2 
61030 Loop to print linenumbers: A recovers ilnk, U recovers upper line 
61040 ends if upper Uinenumbder exceeded, or program's end reached. 
61050 clears screen, prints linenumber, prints GOTO 61030. moves up 
Si 61060 saves link address and puta two returna Into the bulfer. 
70 END causes the loop to defete one line. 


F cenaatictheniint hint. 0 0 sidehoandlnblintatentiabtitate eatedie Beene 
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Diitt 


BASIC command 

PURPOSE: Allocates space in memory for an array of specified name, type, and 
dimensions. The name has two significant characters, the type may be real, 
Integer or string. and multiple dimensions are accepted. Array elements are 
numbered from zero. On setting up, every element of any array is made 0 
if numeric or null if string. 
NOTE: Strings do not need to be individually dimensioned for tength, the 
system takes care of this. So X$(20) is a string arrey holding 21 strings; 
net a single string of tength 20. 


Syntax: DIM name(arith, exp.1, arith.exp. 2,...,avith.exp.nml) (, name 2(arith .exp. 
,-«-}] where the square brackets indicate optional repetitions. Each 
arithmetic expression is evaluated and rounded down if non-integral. The 
permitted range of valucs is 0-32767. High values will generate ?OUT OF 
MEMORY ERROR. See note [3] for information about BASIC L's peculiarities. 
The syntax is not checked thoroughly. DIM T for example does not give 


any error indication. 
Modes: Direct and program modes are both accepted. 


Examples: 12000 Dim PEC(18), L&C8), ALC1B) , SG$C2) 
540 DIMS(B*N + 20): REM B= 2 TO 4. 
$0 Did A(10, 10,10), T(24) ,POSN(X,¥,2): OTM LOCATE (2*¥) , Q(X, 19) 


FOR J<O0T010: X$(J)=STR$(J): NEXT: FOR J=10 TO QO STEP ~1; 7X$(J}: NEXT 


DIM is a straightforward command: the problems associated with it mainty 
derive from the difficulties associated with processing large amounts of data. 
Arrays can be 'dynamicaily’ dimensioned with Microsoft BASIC. This means 
lines like 540 are valid, where an srithmetic expression has been used to 
compute the array subscript size, as well ag jines like 12000, in which 
absolute values are used, Line 540 assigns an array $() 4 dimension which 

is B times as large as another array of dimension N, and adds another 20 
apare elements, In this way, arrays can be assigned by soft-coding to be 

a suitable size for the work in hand. [ine 50 dimensions three muiti-dimension 
arrays, Note that DIM must be repeated at the start of each new DIM 
statement. Finally, the direct mode example shows an implicit dimensioning of 
the array X$(). Although DIM K$(10) is not ineiuded in the line of coding, 
the firat time it ia met during running the trunslator searches for X$(0), and 
when it doesn't find it, sets up the array. The default value of DIM ia always 
10; larger arrays therefore must be dimensioned to avoid ?BAD SUBSCRIPT 


ERRORs. 
Notes: [1] Some general notes of arrays. These notes are long and comprehensive; 
ff DiM and nrraye because of this detail and apparent complex- 


don't be put o 
ity. The basic idea of giving 4 whole batch of data just one name is simple, 


and the method of numbering the separate items isn't too hard either, 

i. Since computer start counting at zern, It is not surprising that Micronoft 
have allowed zeroth clements in their arrays. Some people *consider that 
these elomenta stiuuld not be used, because of possible compatibility problems 
between other versiona of BASIC. Im any program developed for subsuquent 
mini or malnframe use, or with portability in mind, thla Js likely to be true. 
On the other hand, this may be uninporkuit; certainly there are plenty of 
other potential conversion probicms. 7 be zero element, becnuse of bts 
ualquenesa, may hold averaged, totus, comments, or any other summery jtem 
about the array. This exampic ling shows how 4 total might be oullt up: 


Dit A(20): FOR KeiTO20: INPUT W: ACK)SH: ACO)#A(O}4R; NEXT 


ii, (REDIM'D ARRAY ERROR will occur if DIM Iw inadvertently Included within 
a loop. Move it to an earlier part of the program. 


Saee for inutance Oonald Alcoch's '[llustrating pasic’. 


We hae RE Syme ee 


Rae ett eae 
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iif, DIM X(5,0) ia syntactically correct but adds nothing extra to 

except the additional effort of incorporating ‘0' to the Siactiots. Dance ae 
seta up a three-column array, with a choice of C(M,1) or C(M,2) for M = 1 ‘to 7 
(And the zero elements may aiso be used). Two-dimensional arrays, like this one 
are usually visualised as rows followed by columns: A(R,C). ; 


5: BASIC keywords 


iv. CLR seems to delete al! variables and all arrays, an effect produc 

shifting of several pointers. (See diagram). Because of the se Peebles Gre: 
partitioned into simple and subscripted types, it is easy to erase all the arrays 
from memory, whilst leaving all the simple variables untouched. We can achieve 
this in BASIC>1 with: POKE 48, PEEK{44): POKE 47, PEEE(45) and in BASIC 1 
with: P=PEEK (126); POKE 128,P: P=PEEK(127): POKE 129,P. Large arrays consume 
a lot of RAM; this manoeuvre may therefore usefully eliminate a redundant array 
from memory. The ‘Scatter Sort’ {q.v.) provides an example. 


{2} Arcay dimensioning by defoult doesn't only occur when an assignment 
statement refers to a non-existent array value. It happens afso when such an 
array is present in an expression. This program: 0 X=Y=Z;: END when run 
sets up variable X and assigns it the value -1, because ¥ and 2 are both zero. 
Although X is present after the program, neither Y or Z is. But this: 

0 X=¥ =Z(3): END not only sets up X, but array Z2()}, which is given the 
default dimension of 10, This may lead to unexpectedly small reserves of RAM, 


(3} BASIC lL. This ROM has a serious bug, causing an array to remai 

from its 295th element on. Items out of tris range ie weltten wecrele tines 
260th as the fourth) and read back wrongly. This error applies to multi- 
dimension arrays, and causes bugs which can be hard to detect. For example 
remembering to allow for the zeroth element, X(4,50) has 5%51= 255 elements : 
and ¥(9, 24) has 10*25 = 250 elements. Both of thege will process successfully . 
But Z(16,16) has 17*17 +289 elements and will not be reliable. : 


[4] String Arrays. Any previously undefined variabdie will cause all the arrays 
held In RAM to memory-move up, to create the necessary space. This is time- 
conauming and especially so with BASIC 4 string arrays. This is because BASIC 
4 strings each have their own pointer, and these all need updating. To see this 
effect, try DIM X$(1000):A=1;B=2;C=3;D=4:PRINT A. /f this once-only delay 
is important = often it won't be - set up most or ail variables before large 
arrays are dimensioned. For the connectlon between string array dimension and 
memory-freeing time, see Chapter 2 and the section on FRE. Finally, note that 
DIM can be absurdly high with strings, because all the pointers can point to 
the same string: FOR J<O0 TO 1000: X$(J)="ELEPHANTINE": NEXT uses JK oytes. 













POINTERS: End of BASIC £nd of vara /End of arrays 
BASIC<4; ["PAOGKAM | Vara/String paintecs| String arrayf | _ jf Strings | 
pasic 4: [PROGRAM | vare/String polntors[Steime array) [Steinar] 


{5} Storage Space. Space tuken up in RAM can be found wi 

J ace 4 th the aid of FRE. 

P=PRECO)- DI DIM Z¢(500): PRINT F-FRE(0) shows the method, it can be found 

by the formula, for any n-dimensional array: 

ito + cpiine et + 13*(dim2 » 1)" ... “(dimn + £)*2,3 or $ for integer 
g. or real number arrays reapectively. Example: PQ(100,4, : 

$+ 6 + 1019593°S bytes = 7586 bytes. e 7 sae ide 


Abbreviated entry: dI (thls ls why DIRECTORY needs dIR!) 
Token: $86 


Operation: The first character of the: array name Is atored In X, Mont of the work 
Ja dong by the next routine, which searches for the variable, and by another 
routine whieh It cutis, and which §4 extremely long, ‘find or erente array! : 
After thia, If the atutement hasn't ended, DIM luaps back to cheek for a comma 
and repent the operation with the next array to be dimensioned. 


ROM entry points: P 
ie; ¥ POlMts: Hagicy:8cF71 (63108) BASICZ:8CA4 (83081) BASICA:$C121 (49441) 
ad/ereate acray BASIC: $0008 (63493) BASICZ:MUCAC ($4420) BABICS:9C2FC (4916) 
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DUMP 


Utilities unavailable directly in CBM BASIC 
e screen onto psper. 


PURPOSES: (1} A screen dump prints a duplicate of th 
A printer may, of course,be unable to reproduce the full range of Commodare 
characters. Routines of this sort are vaiuable for record-keeping purposes. 
If the screen is built up with POKEs or machine-code a special routine is 
necessary. With output which is simply PRINTed to the screen it is usually 
quicker to direct the output to the printer. 

(2) A dump of variables prints out current variable names and values. 
This is of some use when debugging BASIC. 

Versions: (1) Screen Dumps. Many versions, both BASIC and machine-code, 
exist, Before looking at these, let's consider the problema that can arise. 
Firstly, some characters may be unprintable. Secondly, a printer may not 
use CBM'S version of ASCII. Thirdly, the upper and lower case alternate 
character sets huve to be allowed for, Fourthly. some screens have a0 
columns, others 40. None of these is 8 real problem. (If however some 
non-standard screen display is used, for example a high-resolution graphics 
hardware unit, completely new routines will be needed to dump their screen 


output). 


Early versions, in BASIC, 
did not exist. They conver 


“were concerned with non-CBM printers, which 
t the screen memory characters into outputtable 
equivalents. (See appendix for screen memory and ASCII). Graphics were 
ignored or printed as (say) *. This program, including allowance for 
either graphics mode, shows the type of thing necessary: 

40000 REM ¢** 40 COLUMN SCREEN DUMP ¢** 

40010 OPEN 4,4: CMD 4: IF PEEK(59468)=14 GOTO 40200 

40100 FOR J=-0 TO 24: FOR K=0 TO 49: X=PEEK(32766 + J*¢40 + KE) 

40110 IF X<32 THEN PRINT CHR$(K+64) ;: GOTO 40160 

40120 If X731 AND 2<6S THEN PRINT CHAS(X) 3: GOTO 40160 

40130 If 1128 AND X<160 THEN PRINT CHR${X-64) ;: GOTO 40160 

40140 IF X>1$9 AND X<199 THEN PRINT CHR$(X-128);: GOTO 40160 

40150 PRINT "*"; 

40160 NEET: PRINT; NEXT: PRINT#H4: CLOSE4;: RETUAN 

40200 FOR J=0 TO 24; FOR K=0 TO 39: X=PEEK(32768 + J*40 + RK) 

40210 IF 1¢32 THEN PRINT CHR3(X+96) ;: GOTO 40160 

40220 IF 1231 AND X¢9i TREN PRINT CHAS(X) ;: GOTO 40260 

40230 If X>128 AND X<160 THEN PRINT CHR$(X-32) ;: GOTO 40160 

40240 IF Xy1$9 AND K< 219 THEN PRINT CHRS(X-128).: GOTO 40160 

40250 PRINT "#";; GOTO 40160 


This routine separntes lower-case mode (40200 (f.) from upper-case, and 
js therefore a general purpose routine. Changing the range of K from 
0-39 into 0-79 makes this usable for an 80-column machine, Note, though, 
that BASIC 1 In lower cuse hag its upper and lower coses reversed, 40 
programs written in BASIC i tend to yield odd displays, und odd dumps, 
when cun on other ROM machines. Note that the BASIC subroutine above 
con be compresved, with loss of clarity. Linea 40110 to 40140 can be 
replaced by: 


4010 IF X88 OR (X>128 AND X<195) THEN PRINT CHR$(K-(% AND 128) 
#29¢% AND 32)+847;: GOTO 40190 


and tines 40210 to 40240 by: 
40120 1F X<@1 OR (X>12A AND X<219) THEN PRINT CHASCA~ (X AND 128) 
=pa4((X AND G6)90));; GOTO 40260, 


came mn eee oR CR amen ee Ferre oem tae eee Ne 


pit | eee it 


*CpUCN nos, 64 7 for oxample have « roytins (lower-case Aude only) by J Ajlason 
and M Bennet, 
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beg ithe ae in machine code are newer, K Finn, ('Micro', Aug ‘80} has 
at cat . a version for BASICs 1 and 2, C Brannon (‘Compute!' Nov/Dec 
specail la Compute! Mar '8t) have versions for BASIC 2 and 1 
he ae y- ; e first uses SYS to print the screen; a variable number of 
atroue Wil print the ecreen. This Le valnable if fer sone foacan tee 
: f s is valuable if for some reeso 
Rivero in machine-code) a SYS command can't be issued, or if i act 
@, the SYS command spoils the screen's appearance. ‘ ; 


rid gic Ml (see elsewhere for rationale) is a shart relocatable dum 
oe se kota se characters*are treated as '#'. Upper and ower 
@3 are allowed. It saves tempora } i iD‘ 
it is often helpful to have ine avsivules peridoa in aaaete. 
such a routine availabi ‘h i 
buffer. To use it, open th i as see Baew PROSE 
77 . e printer: OPEN 4,4; CwD 4: SYS 826: PRINT 
7 ahs : . aa: 
pie is an example, when the routine starts at $033A (=826) Three 
ations are marked; these are all user-modifiable. : 


t ‘ 
pa ia ne one ROM address, which prints carriage return and line 
- ae i pe eebasg rae There is no serious difficulty in writing it 
felewine acbadtute ee owever, as it stands, BASIC 4 requires the 


+i €020 AS O01 85 89 20 OF BA AZ 
+»: 6060 &8C DO AD 4C DF BA, 


ad RELOCATABLE BASIC 2 SCREEN DUNP, 


PC IRQ SR AC XR YR SP 
+; Q401 B62EZ 32 04 5E 00 Fa 


++ 6000 AG 00 @5 89 85 8A 85 88 

«t 6008 AS $0 BS BC AD 40 &5 a8 

8 acta ae 83 AS 39 CO 29 DO OF $29 = Max.Colu. +1 

ei 6 8A AS BA CO 1 . , 

-+ 8020 AP Ol 85 a9 20 is 4 ia ue ae ea aa 
+! 6028 00 Al 8B 29 7F 24 88 DO 

~: 6030 06 24 TE FO 13 DO 21 24 

-} €@038 7% DO 09 48 AG 02 2C 4C 

-+ 6040 £8 DO OD 48 AO 23 DO 

+t 6046 48 AQ 02 2C 4c ES DO a a a alata 
; GO50 68 09 40 DO 03 68 O9 GO 

+: GOSS 20 D2 PF £6 8B DD Bl EA 

»: 8060 8C DO AD 4c E2 CS 


2 

oe parable Dumps. ye best known implementation is the Toolkit's 

Meats ‘ 4 Bera routines dump ordinary (string, integer, and 

dunn aor cs ables, but not arrays, which are thought to ‘be t 

cae eas ee 8 no difficulty writing such routines In BASIC; fic 

pricy one ba can simply be printed, Genuraily dumps are designe re 

tere a em aa output to a printer may produce odilitien.. 

61) by P eens oe ta type of dump in Compute! (3#1 Jun 
y : ‘ 8 by putting L2 byten Int , 

Pg ce oO the out : 
trie wiciate Ralls (the zero in intended to represent a null charietaese 
abe pee rate changed in cyclicul sequence, through A AU-A9,, : 
AACAZ,B, BO-B9, BA-IZ,... AGADLADEAAD-AZD, ..«. and at each toop th 
te tout tie bufoe le neine meth routine for tte purpose, Wher a canable 
i" ne : ad, the print routine dete : 

e se os Petia in quotes is printed valeline iar chey 
atlve lyps prints the variables In 
ee bles the order | : 
stored In RAM, {fr other words in their ordur of frst a bythe needa 
. m. 


ee ee 


rr 


ee enn. 
P ei 
Scluding the shifted apace churacter. 
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END 


BASIC command 


PURPOSE: Causes a program to exit to immediate mode. The Ready message is 
printed. This command may be used to set breakpoints in BASIC programs. 
CONT causes 4 program to continue at the next instruction after END. 


Syntax: END has no parameters. [t may be followed by apaces, and must be 
followed by an end of statement byte - either a colon or a zero byte at 
the end of the lne. 


Modes: Direct and program modes are both valid. 


Examples: 20000 PRINT#4,CHR$(12}: CLOSE 4: SYS 45056: SYS 739: END 
853 IF PEEK(32766)<>TR THEN PRINT "*** TRACK READ ERROR": END 
S000 GOSUB 51000: END: GOSUB 58000:END; GOSUB 15000: END 
$9999 END 


Several related facets of the END command are shown here. The first 

A dag line is part of an exit routine, which tidies up the program before 
ending; a control character resets the printer which is then closed, and 
the disk unit is reconnected and a RAM routine called. (None of this is 
standard te Commodore). The second example shows an error-trapping 

line of BASIC which stops the program if a condition is not met: in the 
actual example, a test location which holds en incorrect track number 
enuses execution to end, The third example is not from a finished program, 
but illustrates a way to use breakpoints, Each subroutine performs some 
initialisation function: lowering the top of memory, allocating variubles in 
memory in an efficient order, poking machine code. In the final version 

no ENDs will be present here, but during testing each routine can be 
separately checked, using CONT to continue with the next. The last 
example uses END to ensure that subroutines - located at 60000 and after- 
are not inadvertently entered. 


Notes: £1] Some BASI[Cs require an END at the physical end of a program, even 
if it ends invariably somewhere else. (The last line might be GOTO 1, say}, 
This is carried over from the days when programs were held as stacks of 
ecards, and it was important to separate the programa in a box of cards. 


{2] END leaves the program in memory: other exits. such as calling ROM 
routines to clear RAM, can be employed, If for example it ia feured that 
lines from the program might be accidentally deleted in direct mode. 


Abbreviated entry: eN 
Token: $80 (128) 


Operation: This routine ia shared with STOP; the only difference ia that the 
carry bit ia set on entry to the routine by STOP or by the stop key, but 
is clcared for END. This flag (the curry bit) determines whether the 
message “BREAK IN" pluy Unenumber is printed. With AND, of course, lt 
isn't. Alter the usual ayntax check, the routine tests the mode: if It ia 
direct mode it akips past several instructiona which sve two parameters 
for CONT, the finennumber and the current CHRGET addresa pointer. 
The routina now throws away two hytes from the stack, since it wlahes to 
enter direct mode, and does not need the return address. In the case of 
END ft prints "READY," after londing polnters ta the AAEAK IN .. text 
stored In memory. which of course are unused. Early BASTCH set tthe P/O 
device ta 0, or keyboard, but HASIC 4 docs not, a0 presumiubly CONT may 
be entered from non-CHM devices, 


All the ROMa process thin Instruction in slmitne ways; thea test used in 
HASIC 1 for direct mode {8 different, though, Poecause the input burfer Is 
In Its zero puge, 


ROM entry polnts:BASIC 1: $C71E (30074) 3; SCTAL (OLUOG} 4; IBTCH (47048) 
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EXP 


BASIC arithmetic function 


PURPOSE: Calculates @ (2.718281828...) raised to any power within the range 
-88 ta +68 approximately. The result is always positive, approaching zero for 
large negative powers, and increasing indefinitely for large positive powers. 
EXP(0) is t. 


Syntax: EXP(arithmetic expression). if the expression evaluates to a value larger 
than about 9%, OVERFLOW ERROR will result end the program will end. tf the 
expression is a large negative number on evaluation, there is no equivalent 
underflow error message; the value is simply set to zero. 


Modes: Direct and program modes are both valid. 
Examples: PRINT EKP(10); REM PRINTS 22026.44 ... 
YoEXP(1): REM ASSIGNS ¥ VALVE OF E = 2.7182818 .,. 
PRINT BXP(LOG(N)): REM PRINTS N {POSSIBLY WITH ROUNDING ERROR) 
100 POR N=O0 TO 20: P(N)=(M N)*EXP(-M)/FACT(N): NEXT; REM POLSSON 
200 NT = NE * EXP(-B*EXP(-K*T}): REM GOMPERTZ 
Like SQR, this function is a special case of the power function, and therefore 
is strictly speaking unnecessary. EXP(Q) can be replaced by 2,71828184Q. 
But like SQR it is more easily recognisable in its familiar form EXP; familiar, 
that is, to the mathematically-minded. 


The two first examples are straightforward evaluations. The third reveals 
or underlines the fact that EXP is the converse function to LOG, which {s 
calculated to base e. Whenever a logarithmic transformation has been used, 
Perhaps to reduce the magnitude of the numbers being dealt with, EXP can 
reconstruct the solution, provided that it is within the limits accepted by 
the PET's floating-point logic. 


The final examples are doth formulas; EXP invariably is used in sclentifie or 
Statistical calculations. The first such example is a statistical one; the 
Poisson probability distribution deals with randomly occurring, rare events. 
Given the mean number M of such events (misprints per page, say) line 100 
computes the probabilities of 9,1,2,...,20 such events happening. It uses a 
function definition FACT(N) which is N! op N*{N-1L)*(N-2)* .., "Ll. Chapter 
16 has more on this tapic. Finally, we have a growth curve of the so-called 
‘logistic’ or ‘ogive' shape. This sort of thing turns up in population models. 


Notes: [1] The number e has a farge number of apcclat properties. The rate of 
growth of EXP(X), for example, equais EX?(X),so for small DX, 
(EXP(X+DX )-EXP(X})/DX Is about equal to EXP(X). Malthus’ population 
theory gives a result involving e, which accounts for the popular meaning of 
‘exponential growth’. The infinite series 1+x+x?/2+x1/6+... converges to 
EXP(x). ft (e} ls irrational; only the first few terms appear to recur, * 


Abbreviated entry: eX 
Token: SHD (189) 


Operation: Rather unexpectedly, this functlon does not cnli the power routine in 
ROM, but uses ity own series evaluation method. This Invoivon the following 
sieps: (i) The argument Sa muitiplled by Mloge2. (il) The result la tested for 
Tange. (Mi) The result is normutised into the range 0-1, saving the exponent 
on the stack, (lv) The aceumuluators ore interehiunged. {¥) The serles rauling 
is called; this computes 2A(x flowe2). (vi) The power of 2 i8 added back; the 
Teault ia now eatarguiment), Ati ROMs process (hia instcuction similucly. 


ROM entry points: 


BASIC I: $DEAO (546802) 
BABIC 2: BDEDA (57050) 
BAHIC 4: $0144 (63646) 


* eee tganal’ Beans, mathematically, ‘not expresaidia as a ratio’. 
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FOR..TO.. [STEP] 


BASIC !oop command 


PURPOSE: Permits repetitive processing of afl BASIC between a FOR variable ... 
TQ... [STEP] statement and the corresponding NEXT. When NEXT is 
encountered, the foop variable is checked and, if it matches NEXT, added 
to the value originally assigned to STEP. If the result fails within the 
timits specified by FOR and TO, the loop continues with the statement 
following the FOR statement. Otherwise, BASIC continues Jinearly with 
the statement following NEXT. 

The loop varinbie may be used as a counter, pointer, or subscript, and 
may be changed within the loop. Step size defaults to 1. 


Syntax: The full syntax is: FOR real variable = arithmetic expression TO arith~ 
metke expression (STEP arithmetic expression) . Constructions such as 
FOR / UNTIL and DO / WHILE are not obtainable directly in BASIC, but 
can be simulated by programming. Many FOR loops can coexist while the 
program runs, and they are called ‘nested’ loops, unless NEXT doesn't 
match FOR, in which case vither a loop variable or variables wilt be lost, 
or ?7NEXT WITHOUT FOR ERROR appears. 


NEXT, the end of the loop, has syntax: NEXT [reai variable {,real var- 
fable] {,real variable) ... }. Square brackets denote optional variables. 


Modes: Direct and program modes are both valid. 


Examples: YOR J=1 TO 1000: PRINT “ets: NEXT: REM J USED TO COUNT TO 1000 
POR J=1 TO 1000: PRINT J;: NEIT ; REM ACTUAL VALUE OF J USED 
POR J=1 TO 1000: NEXT: REM DELAY LOOP; ABOUT 1 SEC 


These three simple loops illustrate loop processing with about the minimum 
possible code, In each case J is the loop variable, and in neither case is 

it modified within the loop. Therefore, unless the Stop key is pressed, 

each loop continues 1000 times. Whenever NEXT ts met, J is incremented by 
i, since 1 is the default value of STEP. On leaving the loop, J equals 100%. 
Loops are often used in benchmarks, which provide some indication of the 
speed of execution of 2 computer language. The third example takes about 
a second; the same BASIC operating with the 6502 at a different ctock speed 
will take @ proportionally longer or shorter time. 


100 K=O: FOR J232768 TO 32768+255: POKE J,K: K=K+l; NEXT 
200 FOR f=33768 TO 32768 STEP -2; POKE J+1, PERK(J): NEAT 


Screen pecks and pokes are the subject of the next couple of Icopa; the 
flrat puts 0 to 255 directly into screen memory, starting at the top of the 
sereen, so all 256 ROM chnructers appear. They appear differently in upper 
ahd fower case-modes, of course. The inclusion of K within the loop shows 
one method by which variables can be made to chanye in step with such 
other. This principle is quite useful, Line LOO can in fact be simplified, 
eliminating K, by writing 100 FOR Je@ TO 256: POKE 32768+J,J: NEXT, 

Line 200 is a memory-move routine, which shifts 1000 bytes of the screen 
forward by one location. To do this successfully, It Is essential to begin at 
the top end and work buck, since otherwie cach byte wil be obliterated by 
the provious byte. Thia is the reason for the negative STEP paramster, 
Try the routine omitting the negative step Lf you don't yet see this. 


1000 FOR Jal TO LEN ¢"ADCXCS"): TP INS¢ MIDSC"ABCALS', J,1) THEN NEXT: 
IN$="t" 

1010 REM J NOW EQUALS 1-4, THE POSITION OF [% WITHIM THE STRING OF 
CHARACTERS WE'RE TESTING, OR J EQUALS 7 AND [NB = “?" 


2000 FOR ¥1 «9 ¥t TO ORG; IPF Y1-Y¥71 THEN PRINT#S SOUTHS: NEXT 
Two program exteneta show how IF atutementa wilhin loopa can ba dealt 
with. The first tests Input INS aginst the contenta of # #lring. if INS 
is not found In the string, it’s reset ta a warning valug. Otherwine, J now 
equala IN$'s position within the teat atrlig: this may be ueefial in extracting 
other substrings, Line 2000 in part of a graph plotilag progrem: stop aro 
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drawn southward, from Y to Y¥1, incrementing Yi until the condition fails. 
Finally, we have an example of nested loops. ia which J controts the step size 
between a 2-dimensional plot on the screen. [ have assumed {see SET) thata 
function to draw single ‘points’ exists: 


Notes: 


POR J=60 TO 2 STEP -1: FOR X=0 TO 79 STEP J: FOR ¥=0 TO 49 STEP Ji 
POKE 0,X; POKE 1,¥: SYS 826: MEXT Y,%,J 


[2] Loops in practice are quite easy to use; don’t let the rather tong list 
of notes efface this fact from your mind. 


(2) Syntax. (i) A loop variable must be a simple reat variable: FOR X4 = i TO 
and FOR X(5)=@ TO 10 both cause “SYNTAX ERROR. (ii) A loop is always 
executed at least once, even though strictly, in standard BASIC, a loop like 
FOR ¥«10 TO 1:...:NEXT should be ignored. Apart from taking time to test, and 
thus slowing down benchmarks, the corresponding NEXT has to be found, and. 
in unstructured BASIC, this is impossible. So the example sets V to 1, then 
executes the contents of the loop once. (iij)Inclusive limits apply, so that: 
FOR JxO TO 9: causes J to take values 0,1,2,...,9 and execute the loop ten 
times. (iv) for j=l to 184: in lower-case mode is treated as 1 to 14. 


{3] Accuracy. If the loop variabie and the step size are each stored exactly. 
there will be a rounding error only with extreme values, so a loop will execute 
precisely under these conditions. Generally, integers and binary decimals are 
stored exactly, including the default step value of 1. For this reason, both 
FOR Q=i TO 1000000: and FOA J=.5 TO 1000000 STEP .0625 execute perfectly, dul 
FOR M=1 TO 1000: STEP 1/3 doesn't, as can be seen by including PRINT M 

in the loop, FOR M=1 TO 1000.1 will ensure the count is correct. 


[4] Speed. When fine-tuning a program to run with as little delay as is 
possible, the contents of loops are an obvious candidate for examination. 
Firstly, the variables: the loop variable itself is held by the stack as & 
pointer, so if it is used merely as a counter there is no point in putting it 
early on into the RAM variables. The rule should be to order variables in 
RAM according to their presence inside the loop. When loops are nested, 
the innermost variables obviously should have priority over those within 
fewer loops. The more variables a program has, the more difference this 
will make. Time-saving can be more spectacular with the second approach, 
rewriting the loop(s) to use fewer instructions, or fewer redundant oper- 
ations such as assignments, calculations, or conditions. [t is easy to compose 
examples showing many fautts, and a large speed increase when these are 
removed, but again, in practice, factors of the order of five or six times 
the original speed are not very likely to occur, Let's consider an example 
Incorporating both these factors: 


7600 REM DATA I3 STORED IN RAM IN BATCHES OF 116 BYTES, STARTING AT $6COO. 
7610 REM 60 RECORD NO. R& STARTS AT 27648 + 116*(Rt-1). 

7880 OS(L) a" :0$8(2)="":0$(3)2"":,.. : REM O3¢) HOLDS OUTPUTS 

7460 FOR JeO TO 27: 09(1)=O$(1)+CHRS(PEEK(27648)% 116¢(R4-1) + J)): NEXT 
7470 FOR J=28 TO 47:0$(2)=0${2)+CHAS{(PEEK(27648}+ 116*(RR-1) + J)}: NEXT 
7680 ... 


This progrem extract Is perfectly good and workable, but, owlng to BASIC's 
restrictions, the decision to rewrite it to run faster. may be worthwhile, If 
80, wo ace that ench loop holday conddernble amount of cniculatlon, which 
ean be moved out of the loop, and performed once only. We can une a 
temporary string In place of the arrays, which will process faster; and we 
ean ensure that the variables ace urranged In the optimum order. We get:- 
7680 RI~27648 + L16¢CRA-1}> S$a"" : REM RECORD START POS(TION AND STRENG 
7680 S$="": FOR Je TO 27: SS-+ASCHAS(PEER (RS 9S}): NEAT: OF(1}=5$ 

7070 B9="": POR Jn 28 TO 47:8$-SI+CHHS(PEEK(RSeS)): NEAT: O${2}<99 

7880 .., :;RaM REST ORDER FOR THIS CODE 18 d$~"" RAO: J=o WITH O8() 18T ARRAY 


8% in the moxt important varlible in the religged code, becaurs lt occura 
twice as often an any other varluble. R4, which was very Infuentlal in the 
ortyinal, now ls unimportant as for as this part of the program goon. 
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{5} Nested and structured loops. A nested loop has an appearance which 
may be represented diagrammatically like this: 


And in a program like this: 
First variable 


Second variable 
ee rd variable 


FOR X = X1 70 22: ... 
FOR Y = Y1 TO ¥2: ... 
POR Z = Z1 TO 22: ..: 


NEXT 


NEXT % 
MEXT ¥ wert 
MEXT X la 


Each depth of nesting puts 18 bytes of Information on the stack, and each 
NEXT moves the stack pointer back 18 bytes. FOR and GOSUS share the 
stack; there are limits on the ways they can be used together. Every new 
FOR variable is checked against the current stack contents, and, should an 
active FOR loop exist already with that variable, the stack pointer ia reset 
to that previous loop, erasing subsequent loops in effect. Several ‘nests’ 
can be built within a larger loop, and this is perfectly legitimate and should 
give no bugs: 

POR X=X1 TO X2: FOR Y=¥r TO Y2; ¥OR Z=Z1 TO Z2: NEXT 2,¥; FOR A=A1TOA2: 
FoR 9=B1 TO B2: NEXT B,A,X 

Omission of the loop variables from NEXT (i.e. NEXT:NEXT and so forth) 
guarantees correct nesting. Structured programming has several things to 
say about loops; one ig that there should be one exit point only, and not 
jumping from the middle of a loop to another part of the program. Another 
is the requirement for an explicit exit condition at the start of the loop. to 
make it more readable. The following skeletal loop shows how both of these 


ends can be achieved. it is a . 7 
DO, ..UNTIL loop, starting 100 OR=-1: POR J=BEGIN TO 959 
‘ 110 IF NOT OX THEN J=9E9: GOTO 200 

with ite loop variable set to 
BEGIN and with an arbitrary -+2 PROCESSING ... 

7 150 IF ... THEN OK=-0: REM TEST 
upper limit. ..« PROCESSING ... 

200 NEXT J 


{4] Bug . G) Omission of a negative step: FOR J=100 TO 0: ACJ)=J: NEIT 
Gl) Gmission of NEXT. There ia no 'next omitted’ error. YOR S21 TO MRIZ: 
FOR ¥=1 TO VERT: GOSUB 1000: NEXT. Hoth these errors cause loops to end 
much more quickly than in the correct version. This may also happen with 
(ili) tnadvertent change in the loop variable; this is particutarly liable to 
happen with subroutines in the loop - see GOSUB far examples. 

(iv) The loop variabie(s) may be omitted by mistake; PORT=0 TG A: POR J=Q 
TO 8: X(A,B)sA°B: NEXT J,1 mecds X(1,d)=t*5 in place of the expressions in 

A and B if the ob|cct is to fill the array with the product of row*column. 
(v) An incomplete COSUB (le. with RETURN not yet made) will glve ?NEXT 
WITHOUT FOR, for example; 10 POR J=1 TO 10: GOSUB 20: END / 20 NEXT 

(vi) The upper mit of the loop is stored In the atack; therefore the attempt 
to vary the exit from the loop by controlling it will fuil (ualesa the stuck 


Itself Is altered). Exampte: 106 Awi0: FOR XX= 1 TO A: BEM i.e, 2-20 
110 EMPUT A: PRINT A ; HEM CHANGE A... 


‘ 120 NEXT: REY BUT LIMITA REMAIN 1-10, 
(vil) Use of nonexistent loop variable will give ?NEXT WITHOUT POR; #0 
will NEXT without a loop variable if previous lcops do net exist any longer 
or nover existed. © FOR [= TO 1G: NEXT {I Uacy A non-exlatent variable; 
0 NEXT has no corresponding FOR; and O FUA I=1 TO 10: POR Jal TO if; 
NEXT I: NEXT oliminatus J by its reforence tw f, vo nothing is jeit for NEXT. 
{7] Logical variables, DO WHILE foopa can be slmulated itke this: 
FOM J = <1 T0 0; ... 1 J = TRST EXPRESSION: NEAT 
Where the omitted proconalng ia performed until J becomes falad, 
Abbreviated entry: (0 atZ. Thoro Is no shart form of 'TO’, NEXT has nF. 
Tokens: FOR $8) (29) TO $A4 (164) STEP SA% (169) NEXT 482 (199) 


Operation: See NEXT for operation of the atack and ROM entry polnts, 
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FRE 


BASIC arithmetic function 


5: BASIC keywords 


PURPOSE: Computes the number of bytes availah’e to BASIC between the end of 
the array storage and the start of strings. FRE first performs the 
so-called "garbage collect’ routine, which rearranges all the strings held in 
Upper RAM into one consecutive block. This is useful when dealing with 
strings and string arrays, dDecause (unlike numerals) they occupy variable 
apace in RAM. This function measures the free memory. 


a sca FRE(expression). FRE ig a function in the sense that it returns a value. 
ee bese wear PRED a dummy. Typically, PRINT FRE(G) or F-FRE(1) 
. u n{X), FRE(X$), or FRE(AR(S i 
correct versions of the function. ia aac 


Modes: Direct and program modes are both valid. 


Examples: PRINT FRE(O) 
LOQ0 PRINT FRE{G) “BYTES AVAILABLE AT PRESENT” 
200 Z=FRE(O}: DIM Q$(75): PAINT (X-FRE(O}) “BYTES USED BY POINTERS" 


The first two examples, in direct and program mode respective] l 
print the free memory, The third is a more elaborate mp of San ai 
demonstrates the use of FRE to measure the differences before and after 
some memory-using statement(s). Thia example prints the amount of RAM 
taken up with the pointers for a string array of dimension 75. 


Notes: {1] This diagram illustrates the situation, if a new string is defined 
which, even after garbage collection, is too long to fit into RAM, an ?0UT 


OF MEMORY ERROK message is printed. 
Top of BASIC RAM 


[variables] arraya | PRP peor 


This example program shows how rapidly RAM can fey this 

: i J ; ‘ e@ used; this ts part of 
an input routine which gets single characters in order to exercise gedatak 
control over the permitted input than is allowed by [NPUT: 


5S GET I$: IF Xk$="" GOTO 5 
10 I$mE$sX$: GOTO 5 


Each X$ takes one byte, and each I$ occupi 

. pies one more byte than it did 
previously. A string of length n takes $n(ned) bytes. using a little aig- 
ebra, So for example a 20-character input occupies 230 bytes. 





{2] with no i 
Program in memory, FRE returna the number of byt f 
end of the program; so after Commodore's BASIC remaae: wind GAN) 
1743 bytes free, PRINT FRE(G) prints 31740 or 31741 depending on the 


ROM. Lowering the top of memory by POK i 
bytes. returiaa by ere. ry by POKEs will reduce the number of 


{4} Timing. Thia ls a well-known problem associated c 
A program using DIM X$(512) will intermittently stop th wahags paisa e 
rll haat atring spsce is short, not only on executing FRE, and the process 
slow, (BASIC | han the same problem; but people were cautious of large 
arrays, which didu‘'t work correctly), The time taken to free memory is a 
function of the number of strings in upper RAM; It la a aurpreisingly preclae 
relationship, and ia about .00008 * (N+11}? seconds with BASIC<4. See 
Chepter 4 on ways of minimialng thia delay. One of the features of BASIC 
4 is that the strings are held differently and freed more quickly. Chapters 
2 and 4 give details. The following program, which can be entered in 
direct mode, lw about the worst caxe with HASIC 2, and runs in 83 minutes: 
Dim A$(7G00) : PORS«0T07 900: ASC S) <CHR9 (1): NEXT: TeTI; JePRE(O): 2(TI-T)/60 “SECS” 


5 . 
Peration: The function flratly frees memory by cailing (he garbage cotlect aub- 
ance eae subtracts the polnter to the end of the arrayn [rom the 
nter to the bottom of the strings, und conv , 
Dane Ge CarueLcee at. K erte tha result Into floating 


Ro 
M entry polnte: BASICL: $0264 (83060) BASICI;9O25E (59849) AASICA:$CAAS (50344) 


mapa, 
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GET & GET + 


BASIC input command 


PURPOSE: GET and CET# read a singte byte from the keyboard and from any 
device, respectively. In the case of the keyboard, if there is no character 
in the keyboard buffer a nutl string or numeric value zero is returned, On 
entering CET or GET#, the status byte ST is set to zero; the end of a 
correctly CLOSEd tape file sets ST to 64, and the end of a correctly CLOSEd 
CBM disk file sets ST to 64 and in addition sets the byte read by GET# to 


Carrlage Return. 


Syntax: GET (#arith. exp. ] var. name [,var. name][,var. name] ... ; 
GET may optionally be foltowed by # with a fogical file number which muat 
evaluate to 1-255. At least one variabie name must follow. The processing of 
GET resembles INPUT (q.v.) in its use of the input buffer, but no extra 
parsing is carried out on GET’s single byte, so this command may be used to 
input any data, untike INPUT which presumes certain formatting conventions. 


Mode: Program mode only. Direct made generates *ILLEGAL DIRECT ERROR. 


Examples: 5 GET X$: IF X$="" GOTO 5 
10 PAINT "[UP)"X$" [LEFT] (LEFT](LEFT}" ASC(X$); GOTO 3 


200 GET A$,6$,C%: PRINT A$B$C$: GOTO 200 


If you're uncertain about the function of GET, these examples, when RUN, will 
soon give you the idea. The first prints XK$ and its ASCII! value at a fairly fixed 
position on the screen. where X$ is the single byte returned by GET. You will 
be able to observe how GET can accept a carriage return, for instance, which 
hae the ASCII value 13. This is an infinite loop which Stop can terminate. Line 
100 is a similar loop. The syntax is more appropriate to GET#; however, if you 
are quick, more than one variable will be set from the keyboard. The method of 
Ine § {8 necessary if a keypress is awaited. It is the starting-point for 
crashproof input routines; see Chapter 4 on this topic. 


$5 GET A is valid. However, apart from 0-9 which set A=0-9 a3 expect- 
ed, *2YNTAX ERROR is printed, or 79EXTRA IGNORED with ‘ and >. Also, 
space,t,~, and E return 0. It's usually best to GET a string variable. 


ee 
2000 GETS, X$: IF ASC(X$)=13 GOTO 3000: REM STAING IN$ IS COMPLETED 
2010 IN$=IN$+I%: GOTO 2000 ; REM BUILD STRING INS 


This example shows how a string !s¢ built up from successive bytes. 


Notes: [1] The Keyboard Buffer. GET (provided that an input device number is not 
found by SFFE4) takes one character from the keyboard buffer. (Characters 
are put there during IRQ servicing). This buffer occupies 10 bytes from Labeda 
(623 ff, dec.}, and $9E (158 dec.) indicates how many characters are present; 
if , the null charocter ia assigned toa string varinble. BASIC 4 has 4 variable 
length buffer: $£3 holds ita greatest length. LINENG GET X$: TF X$>"'“GOTOLINENO 
empties the buffer. So dors POKE 158,0 although this Is reversible: POKE 158 
with some non-zero nuinber revives characters in the buffer, In faet, poking 
158 with 200 in direct mode prints the entire contents of cansette buffer al. 
Apple has a different end inferior GET which wuits for a keypress. The short 
routine which foltows can be used to test any BASIC for keybourd buffering: 


10 POR J = 0 TO 3000: NEXT: POR J © 1 TO 20; GET X$; PRINT 3:9: NEXT 


When RUN, this delays for a frw seoanda, then GETa and prints out characters, 

If several keys are pressed in tien during this rtolny, they will, with CIM 

machines, be printed later, showing that 9 buffer exists, The buffer can hold ten 

keys, and it it casy to demonstrate that BASIC<4 erusca the buffer und starts 

over {f more keya than thla number ary preased. This has a practical effect 

on crashprouf input routines, Note that WASIC 4 retalas auras keys, and 

Ite buffer need aut be 10, POKE 227,0 for axample tucks out Iho keyboard 

altogether. beds Tet an Saley -athouie alent Mille Adiihen neers 

SUnlike INPUT# and PRINTS, GET# haa no separate token, no I've treated it with GET. 
*BASIC 4‘ heyboued buffer ja get to 10 characters on power-up, but it can be changed 
by a poke. BAGIC 1's buffer begins at $0O20E, and contains $020D bytes at any instant. 
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[2] Tape. The tape reading routine is part of $FFE4, {t can be recognised 
in R after the point where the input device number is compared with #3. 
After this point, the carry bit is clear for both tape devices, which are 
numbered 1 and 2 by Commodore. The character is taken fram the cassette 
buffer (i.e. 192 bytes from $027A and $033A). When the Suffer has been 
read, everything pauses while the next dlock from tape is read inte the 
buffer, and its pointer reset to start. The end-of-file marker is a zero byte, 
which will cause ST to be set to 64 as the last character is read. If this is 
not detected, the next GET# (or any other input/output command) resets ST 
to zero, so the cassette will keep reading further data. 


(3) Disk. Whenever ST is set non-zero, a carriage return character is sent, 
except with BASIC i, which sets ST but returns the previous byte. It is 
not only EO! (end of file, in effect) which sets ST; time out on read has the 
same effect, so slow devices may send only carriage returns. The time-out 
feature can be disabled in BASIC 4 {by POKEing $03FC with a negative 
amount, e.g. POKE 1020 ,128). Typically, therefore, this type of routine is 
ueed with GET#: 


2000 IN$="" 

2005 GET#8,X$: [F ST=64 OR ASC(X$)=13 GOTO 3000: REM EXIT WITH IN$ 
2010 INS=IN$+I$ 

2015 GOTO 2005 


(4] Since GET# takes in colons and commas and so forth, it can be used to 
check @ file's contents in a way impossible with INPUT#. Moreover there is 
no limitation to B80 characters length, although a built-up string like the one 
in the earlier example cannot exceed 255 characters in length. BASIC<4 
include carriage returns when using GET# from the screen; each GET# which 
was a multiple of 40, e.g. the 40th, 80th, etc,, became CHR$(13). But GET# 
from the screen is rarely used. Note also that the difference between GET 
and INPUT as regards cursor Mashing is determined by the number of bytes 
in the keyboerd buffer, but this may be overridden by POKEing the cursor 
flash location with the value zero. This location is $A7 (167) in BASIC>1, 
and 30224 (548) in BASIC 1. 


Abbreviated entry: gE a gE# 
Token: $A1 (161) 


Operation: GET and GET# use the input buffer, but place a zero byte Into $0202 
60 that a single character onty is taken. The ‘get’ part of the routine uses 
the kernel routine at SFFE4, which returns with a character in A and with 
8ST possibly set. There Is also an assignment part te the routine, which 
shares ROM with READ and [NPUT. I[f the '#' symbol is found, the number 
or expression after lt ia worked out and this logical file number is stored 
for future use in $03 (BASIC 1), SOE (BASIC 2), or $10 (BASIC 4). When 
the byte has been fetched, normal device input/output is restored, 


ROM entry points: 
GET; BASIC 1;$CAQF (51871) KEYBOARD BASIC 1:$E2B7 (58039) 


BASIC 2:$CA7D (51837) PRTCH: BASIC 2:$£288 (58040) 
BASIC 4:$BB7A (47094) BASIC 4:$3£009 (57347) - NEEDS SEI. 
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-= 
30 
ASIC dummy command ea ah 
. to perfor 
: Sote function is to look for a matching TO, and, found, 
sere TO. The raison d'etre is to provide GO TO as well ag GOTO in BASIC. 
yntax: GO must be followed by one or more spaces, TO, and a linenumber. 


lotes: [1] BASIC 1. This token {g not present en etre PET elit a 
facility to eliminate spaces on tokenisat on, so tha nvert 
itueif to GoTo. This method of forming tokens leads to more ania 
than the later method. Possibly for this reason, it was changed, so tha 
line like: 
10 IF 258=LE THEN PRINT "HIGA” 


ET. However, GO TO was also eliminated, 


no longer appeared to contain L «GO and a special routine to 


and a patch pul in, consisting of the toke 
check that it was followed only by TO. 


hines, using GO TO, will 
follows that programs developed on later mac’ 
fe LIST pronerly with BASIC 1; GO producea "SYNTAX ERROR. 


sed along with other 
4, GO is no tonger & patch, dut processe d ; 
ee ane versions appear to be defective. An early manual ee ROM 
statea that an extra byte or token must appear between GO and 
compensate for a bug: GOXTO for example, or GO TO TO. 


i haps es a command in 
an be intercepted by a wedge and used per 
De eouted GOSUB or GOTO routine. See Chapter 14, section 14.3.2. 


{4} GO causes problems with some renumber utilities, which haven't allowed 
for the existence of this token. 

Abbreviated entry: None 

Token: $CB (203), Not present in BASIC 1, 


Operation:In BASIC 2 the routine ta execute a BASIC statement is at $C700. 
. The patch to process this command is at $C72!. 


In BASIC 4, the entry point for GO is SB7AC (47020). 


Sn ee TE RP 2 RE EYE IT 


ee) ace 


orange Bie 
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GOSUB 


BASIC command 


PURPOSE: Performs a jump to any line in a program. The target line is identified 
by its linenumber, When RETURN is next encountered, control is transferred 
to the statement following GOSUG. in association with 1F or ON, conditional 
calls to subroutines may be made. 


Syntax: GOSUB linenumber. The linenumber must be ASCI[ numerals (e.g, 1234), 
and, like GOTO, the first character outside the range 0-9 marks its end. 
Computed GOSUBs of the type GOSUB x need to be specially written. If 
the line doesn't exist within the program, a run-time error will occur. 


Modes: Direct and program modes are both valid. A subroutine in a BASIC 
program in memory can be tested in direct mode. 


Examples: 4 FOR ¥=Q TO 24: FOR A=O TO 39: COSUB 1000: NEXT; REM HORIZ & VERT POSNS 
1000 PORE 245,¥: POKE 226,H: S¥S 58843: RETURN: REM FOR BASIC i 


G4 2024 IF AIGHT$(JS$,1)<>CD$ THEM EM$="IN CHECKLETTER": GOSUB 12000 


Ait 22000 PRINT “[HOME)(23 DOWN)[10 RIGHT}(RYS]*** ERROR " EMS “ (RYSO]"; 
120190 FOR J=OTO2000: NEXT: : REM DELAY LOOP 
12020 FOR J=1 TO LEN(EM$)+11: PRINT "([LEFT] [LEFT]";: NEXT 
12030 GOSVB 100; FOR J=) TO JL: PRINT " ";: NEXT: RETURN 


iv $00 GOSUB 510 
$10 REM ** SUBROUTINE TO BEE? BELL ONCE ** (Detail omitted) 


i, This first example shows how a subroutine may be called in direct mode. 
Line 1000 is a subroutine which positions the cursor, using 2 parameters, 

H and ¥. The dircet mode Jine performs an exhaustive test on it. 

il, The same piece of code may be required in many different places within 
A program. This use of subroutines - one of the most important ~ is 
exemplified by tine 2024: on discovery of an error in a check digit, the 
parameter EM$ is set to a suitable value, and the subroutine called. In 
other parts of the program the identical subroutine is called, but EM$ takes 
other literal values: “IN SALES CODE", "- NOT ON FILE", and so forth. 
iii, This four line routine prints an error message in reverse on the bottom 
of the screen, and erases it after about 2 seconds, Then, in line 12030, it 
calla another subroutine, which in fact moves the cursor to the position on 
the screen which the operator is using for input. The erroneous string. of 
length JL, is erased ready for reinput. 

iv. Thie is a simple example of the une of subroutines with multiple entry 
Points. GOSUB 510 beeps the speaker, GOSUB 500 beeps It twice. 


Even when code [s used by only one part of a program there are many 
situations in which subroutines improve the total program, Here are some 
examples: 


¥. Programs written in a structured or semi-structured fashion can have 
tontroliing routines written jike thie: 


7000 IF Ja$—"s" THEN GOSUB 2000; GOTO 6000; REM SKIP TO NEW ITEM 
7010 IF J8gu"B" THEN GOSUB 3000: GOTO 6000: REM BOOK STOCK IN 
7020 IF JS$e"E" THEN GOTO 4000: ARM EXIT AND CLOSE DOWN 


vl, Any routine which Is too lung for one Ilne, or requires multlpic IFs or 
6ther confusing constructions, may be easier to deal with as @ subroutine. 


vit, Batenes of similar routines may be clearer when written an aubroutines, 
8) that a block of the program collects together in one place 6 sct of 
closely related procedures. 


600 PRIRT "(";; GOSUB 400: PRINT ")": RETURN: REM INDIRECT JUMP 
#10 COSUB 500; PRINT ",¥"; RETURN: REM ZEROPAC?,Y 


620 PAINT "(";: GOBUB $00: PRINT ",%)°: RETURN: REM (ZEROPAGE ,X) 
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Abbreviated entry; goS 
Operation; The atack is teated. if 





$: BASIC keywords 


GOSUB are dealt with by the svanning routine 


Notes: (1] Linenumbers following ; 


which GOTO asiso uses, The effect is similar to the VAL function. This 
incomplete validation allows ON ... GOSUB to function, since A comma has 
to be treated as a marker for the end of linenumber. It permits some odc 
anomalies, which also occur with GOTO. For example, ali the following 
commands are interpreted GOSUB 9:- 


GOSUB GOSUB REM NEW cosus {PI] , 


GOSUB Oxxx 


and 
GOSUB LOQONEXT GOSUB 50*2 


are interpreted GOSUB 1000 and GOSUB 50 respectively. 


[2] Timing: Since subroutines can be called from any part of the program, 
it ie desirable from the speed point of view to put the most commonly used 
of them at the start of the program. This minimises search time for the 
linenumber. (RETURN stores a pointer to the original GOSUB, so there is 
no search, time spent in RETURNing). Program structure of this type ia 

a 


therefore common: GOTO 5000 
100+ Standard subroutines 


Menu options 1,2,3,... 
S000+ Initialisation 
Manu for all options 

Closedown and end 
OO00+ Initialisation, closedown, 
and utility subroutines. 



























[3} Note that GOSUB 500: RETURN haa the same effect as GOTO 500. 


[4} See text for computed GOSUB routines. 


{5] It is sometimes useful to escape from a subroutine without returning 
to the previous GOSUB. See POP in this reference section for details. 


{g] A program with subroutines is inevitably fragmented into discrete 
chunks, so subroutines may need to be isolated from the remaining program 


to prevent dropping-through and execution of subroutines at the wrong 


time. For example, with subroutines starting at 60000 the line 59995 END 
guards against this eventuality. Subroutines can call themselves, but an 
exit mechanism of some sort is necessary. 100 GOSUB 100 for example will 
generate an 70CT OF MEMORY ERROR as the stack fille up with return 
addresses. When handied correctly, this technique is called ‘recursion’. It 
fa used widely in translaters and compilers. [ncidentally, the claim that 23 
levels of subroutine can be handled by CBM BASIC should be treated with 
caution. All intermediate results, and Inops, are pushed on the stack, 80 
a subroutinewith loops and many parentheses may unexpectedly run out of 
memory with far fewer than 23 subroutine levels. 


Token: $8D (141) 


there is not room for 6 bytes an 70UT OF 


MEMORY ERROR message appears. {Although it only uses 5). Assuming 
thia test is passed, 5 byfen are puphed onto the gtnck: the current CHRGET 
addreas, the current Hnenumber, and a GOSUB token ($8b). After thls Its 


operation Is Identical to GOTO, [t scuns linenumbers in the sume way ad 
GOTO, either from the start of the program or from Its current position, 
depending on the Hnenumber, Flnally tt carries out a BASIC warm start. 


Btack use# demonstration program:- divos:- 
To P9170." cosua 20 o p 104 498 
90 PRINT PEXK(P),: PeP-1: IF PuGOO THEN END Gq 14) ini 
Jo GOTO 40 “a4 ' 
Tohaty Location  Liadnueber 


ROM entry points: 
BASIC 1: 9CTSO ($1073) 


BASIC 3: $C700 (61088) HABIC 4: $BH13 (47123) 


ye rt 


| 
| 


_— 7 


Sep eyes or 


pete 


0 ee 


+ pene ge 


i 
! 

a 
zt 
2 

‘ 
z 
g 
5 
‘ 
4 
t 
t 
{ 





Progromming the PET/CBM -73- 


GOTO & GOTO 


BASIC command 


5: BASIC keywords 


b j ji . fi t b label. ft jati ith IF 
¥ its inenumber ; ret, for exampie, ¥Y & label. [mn association wit of 


QN , conditional ju 3 ! 
to go to. jumps may be made, setecting which part of the program 


Syntax: i 
y ge 4 a or petites followed by a linenumber. The lnenumber must be in 
- Bates ITO 1234). Computed GOTOs of the type GOTO x need to 
ae ar Paiateia Note that the linenumber is processed in a similar wa 
acheter ta unction ; the first character not 0-9 js deemed to be the final J 
r the linenumber. Nonexistent lines cause ?7UNDEF'D LINE ERROR 


Modes: Di 
es the ae aed program modes are both valid. Direct mode will cause a jum 
aa san bl eta in memory, and, provided the target line number cpieks E 
ee ice gue by tie cee point of entry. Since CLR isn't performed 
; gram are unaltered: thi 
resembles CONT and is usable after STOP, END. cancer 


Examples: o$="022983": GOTO 12000 
100 GET X$: IF X$="" GOTO 100 
GO TO 100 


aoroce aaa a shows a direct mode GOTO statement. Before executing 
poeein eb tae is set; in the example.with an invalid date, to test the 
Aikikai jproeren. Any line may be jumped to, including itself. The 
indefinitely ee a con itional loop which, until a key is pressed loops 
oe CHEE ao che atcer yeu 100 wil constitute an infinite toop, 
ilustrates that GO TO is an scoepistle variait-or GOTO. ies dai asd 


Notes: [1] On the subj i 
ject of the differences between GOTO 
: a 
reference page dealing with the GO token. Generally, GOTO Wx betice, as 


2] Some apparent anomalies resul 

é e sult from the translator! i 
aes the preted following GOTO. GOTO 1010, with i Gercdccliaiy. fac 
L os . ty pias Say 1, does not preduce a syntax error mesaage, bur 
GOTO 0, And the qclltuey AUGER GOTO HE nis mean Gore G:C 

is tak 

poking a null character into a linenumber, GOTO 200 mey & onde th 
as GOTO 20 but act like GOTO 2. Ue anes 


{3j Timing: the time spent searchin 
g& for the target linenumb 
ML keke oc ee: notably Sharp, are far alone houavan nae 
‘ n ‘ 
is Peoaapetiky ecessary to know how GOTO is processed, This 
) The high bytes of the line number 
igh 8 (and only the hi 
ihe cunts 1k if the target linenumber is larger by chin teak. linea’ati@r 
Bike fear ithe are scanned; (ii) if the target linenumber is not larger - 
Bante: asso canG f ee tecere 4 ae are scanned. To take a concrete 
teen RAGE cL ae Soiani : , and 25600 GOTO 25825 all have 
#- 25600 GOTO 25 i 
on the other hand, scan forward from their ciel palin ere 


P {4} See the text for computed GOTO routines, 
bbrevlated entry: gO (-GOTO) Token; $89 (137) 


Q .4 ¥ 
ei eaigh ad has sbtaiar is fetched one character at a tlme and converted Inte 
rie 4b oe The process stopa when a non-numeric character Is found 
bie keg “a of the next line in calculated, Now, In x GOTO y thes hi h , 
picked cde Raa stay with tho high byte of x: If larger, Ninen are ene 
Ao lee pci taser sane bs sought frem the start of BASIC, tf 
wo EF'D LINE Ia branched to; oth re 3k 
is pulnted to the zero byte Just before the target dine. ane omen 


ROM en 
try polnts:BaSicl:$cT90 (51101) BASIC2Z: $CTAD (81127) BASICE: $BAIO (47154) 








aro 5: BASIC keywords 
Programming the PET/CBM 74 


HTAB & VTAB 


BASIC commands unavailable directly In CBM BASIC 


he screen, as specified by 
3 ves the cursor to any position on the , as 
sie Sati and/or vertical parameters. This is sometimes called PRINT @ 


SIC. All that is needed 
i : i f function is easy to write in CBM BA 
Meee i orntsaatenient including [HOME} and 8 suitable nunber So hey 
and cursor right characters. Machine code routines can aarp ha 7 
e faster than the BASIC equivalent, which may be impo Bi esi 
el umstances. For example, @ formatted screen which inputs ai : He 
validated information may well be Reach nite oat ak pana 
i e ROM routines responsivie ‘ 
taint oetiner ‘aned at switchon, must format the age a een 
hine dependence, though, has to be ta ac i 
SE each BOM HAG its routines in a different place, set in silicon. BASIC 
4 has two versions! 
: 6843: RETURN 
C 1: PORE 226,H: POKE 245,¥; SYS 5 
asic 2: POKE 196,8: POKE 216,¥: SYS 57949: RETURN 
4 
Mab Coby: POKE 198,8: POXE 216,¥; SYS 57471: RETURN 
BASIC 4 
(80 COL); POKE 226,F: 
Note that the 8032 is more a 
types of screen editing. Thi 
acrotling window. 
i follows. Line 1000 holds the 
7 emonstration program in BASIC 
apse Sih subroutine, and corresponds to BASIC 2, but any of the 
routines listed previously can be substituted for it. 


The 


PORE 224,¥: SYS 57439: RETURN 


i 1 
Ifficult to deat with because it has severa 
s version resets the top left corner of the 


. = eee RUN 10 USES SYS COMWAND TO POSITION CURSOR AT H,¥ **** 


$ REM *#e* RUN 20 PRINTS CURSOR CONTROL CHARACTERS **** 
THE DIFFERENCE IN SPEED . 
non ¥=0 ai POR Hx0 TO 39: GOSUB 1000; PRINT “(birt &]";: 
NEXT H,V: BND 
20 FOR ¥<0 TO 24: FOR 
NEIT 4,¥: END 
: : URN 
98,H: POKE 216,V: SYS 87949: RETURN 
iooi opel ay oe FOR JmQ TO HB: PRINT "[RIGAT)";: NBXT: 
Fok Ju0 TO ¥:; PRINT “[DOWN]";: NEXT: RETURN 


W=0 TO 329: GOSUB 1001: PRINT “[abift &]";: 


| 
| 


ee eee ee 


epee ree 


+ emer me remee 


A rr tt ag 


tad 


ee ary 


i 
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5: BASIC keywords 


BASIC conditional command 


PURPOSE: Allows {i} Conditional branch to any program line, 


{ii} Conditional execution of statements following [F. 


Syntax: IF arithmetic or logical expression THEN linenumber or statement(s) 


GOTO linenumber 
THEN may be followed by a null statement: iF X=1 THEN: is valid. 
On execution, if the expression evaluates to 0 it is treated as 'false' and no 
further part of the line is executed; if it evaluates to any non-zero value 
it is regarded as ‘true'. This fact enables the conditional expression to be 
arithmetic, not just togical with alternatives 0 and -1, See also note [1]. 


Modes: Direct and program modes are both valid. 
Examples: FOR N=] TO 1000 STEP ,01: GOSUB 100: IF VAL(N$)=N THEN NEXT 


Thia direct mode exampie is being used to test a rounding routine; if the 
condition fails, the loop ends and PRINT N displays N's final value. 


500 IF P=60 THEN P20: GOSYB 30000: GOTO 600: REM PAGE THROW 

700 IF I=1 THEN IF A=4 AND B=9 THEN PRINT'*"; :REM SPECIAL VALUES 
800 IF 7+6 GOTO 900 

1000 IF 8 AND 7 THEN THIS IS NEVER REACHED! 

1200 IF YN$="¥" THEN: $D,1 : REM BASIC WEDGE IN USZ 


This batch of examples illustrates most points relevant to [F. Firstly, its use 
in conditionat execution of BASIC: if 60 lines have been printed, the counter 
is reset to 0, a subroutine to cali form feed and print a new heading is run, 
and the processing resumed. None of this is done if the condition was not 
true. Line 700 contains a composite [F; this is entirely valid since THEN may 
be followed by any statement. Note that 'IF X=i AND A=4 AND B=9 THEN’ is 
exactly identical in its effect (but slightly slower}. Line 800 causes an 
unconditional branch to 900. This is because 7+6 evaluates to 13, which is 
hon sero. Line 1000 is the opposite; anything after THEN cannot be reached 
by BASIC running normally. Finally, line 1200 demonstrates a point which is 
sometimea important with wedges in BASIC which add extra commands. Here, 
'$’ signals a special inatruction (disk directory with Compu/think disks) which 
if intercepted by the wedge will carry out the command, even when the IF 
condition is false. The colon, starting a new statement, prevents this. 


Notes: [1] IF .. GOTOn 1s of course redundant; It can always be replaced by fi... 


THEN n. However, It ia sfightly faster, Note that IF .. GO TOn js not valld, 
while IF .. THEN GO TOn ist IF .. GOSUB n js not allowed, and must have 
THEN. On the subject of syntax,note finally that GOTO doesn’t validate the 
inenumber fulty, so that IF A=B GOTO 10XX will branch to line 10, 


(2) IF X THEN... is the same ag IF X<>0 THEN ... and vice verna. 


(3} Rather atrangety, a condition may include strings, which on ‘evaluation’ 
may not use the floating point accumulator, so that the previous calculation 
determines the ‘truth' of the conditlon, Q9="":1F x9 THEN: Is false, while 
QdaCHRGI(1}: IP XQ THEN: in true. 


(4} Some BASICs, notably [DM's $100 serios, allow only IF .. GOTO, resulting 


in exceptionally apaghettiod progroma. Apple Inteyor BASIC akips to the noxt 
Statement, not fine, after a falue condition, 


Abbreviated entry: None Token: $868 (139) 
Operation; This short routine evaluates the exprassion after IF, then checks for 


GOTO or THEN. If one of these is found, tho exponent of accumulator #1 In 
examined. Uf zoro, i.e, ‘falxe’, the noxt line in jumped to, using a routine la 
common with HEM. If non-zero, lu. ‘true’, the noxt character in checked; if 
it's a numeral, GOTO in catled; if not, the next atatement la executed. 


ROM entry points :BASICE: @C820 (51934) BASICI:$CHIO (61248) BASICS: OBABI (47283) 








‘ragramming the PET/C&M -76- 5: BASIC keywords 


INPUT 


JASIC input command 


%URPOSE: Provides users with an easily-programmed method to key In data from 
the keyboard ta the CBM. (tNPUT accepts data from the keyuaard and 
echoes it as output to the screen, untess the input/output devices have 
been changed, for example by CMD. INPUT# is an alternative form which 
is designed for input from tape or disk file storage. Input is terminated by 
the ‘Return' key or by the ASCII character for 'Return'. 


syntax: The iNPUT statement itself has this syntax:- 

INPUT [string literal within quotes;] var. name [.var. name][,var. name]... 
When RUN, this statement prints a question mark followed by a Mashing cursor 
to prompt the user, The optional string is printed before the question mark 
onto the screen. Thus, INPUT X$ and IWPUT "CODE"; X$ are each valid. The 
first prints ? with the cursor, the second cCobE? and the cursor. Subject to 
the rules which follow, the variable X$ will be assigned, on Return, the data 
typed after the cursor. Note that the optional string must be within quotes 
and ia not a string expression. If X$="NAME", nevertheless INPUT X$:N$ 
generates SYNTAX ERROR, presumably to avoid confusion with [INPUT X%. 


The keyed-in data is processed according to these rules:- 

(i) Alphanumerics are dealt with straightforwardly, but many characters are 
not, notably ", : Return and the screen editing characters. The quotes mark 
* wets a flag causing subsequent input to appear as a literal, so that Home and 
Delete for example appear as they would within a literal, without homing the 
cursor or deleting the previous entry - Other special characters, such as , 
and : may be incorporated into string input in this way. Carriage return, 
however, always terminates (NPUT and turns off quotes mode. An opening 
quote, with or without 4 later closing quote, is therefore a valid entry in 
response to [NPUT's prompt; but quotes in the middle of a string entry gener- 
ate ?FILE DATA ERROR (or ?BAD DATA ERROR in BASIC 1). INPUT shares 
routines with CET and DATA and, like them, relies on the comma a3 4 separ 
ator and the colon to mark the end of a statement. These are treated as 
separators with INPUT. ?EXTKA IGNORED wii) result if the separators seem 
to indicate that there are more strings of input than corresponding variables 
to assign them, The double prompt 2? js printed when INPUT has had fewer 
strings of input than it has variables. Leading spaces are ignored. 


Ui) When the input doesn't match the type of variudle to which it is assigned, 
REDO FROM START appears and the Input is repeated. There are minor 
exceptions to this. An integer variable may be assigned @ non-integer value 
without an error message, and 4 Teal variable may be assigned data in scientific 
format, 


(Hi) ENPUT takes in ell the charactera following the prompt to the end of the 
Hne. Consequentty tt ia difficult to use INPUT with a screen neatly boxed 
with graphies. (It can be done by editing the resulting graphics input out of 
the string). And the totul length of the string ix limited by the screen width 
to 39 or 79 characters, when 4 prompting string lan't used. 


(lv) Finally, CBM's notorious Input crash, which alone [s sufficient to make an 
unmodified INPUT unsuitable for many applications. If 'Return’ only ls pressed 
in response to INPUT's ? BASIC prints "READY .’ and stupa. It can be 
revived by CONT without loxs of data. Aclunily, this Is true only if no file 
appears to he open to INPUT, and like SPCC and TABE, this feature can be 
changed by POKa. See nots [2]. Note: VIC hus ne bipet crash? : 


Mode: Program mode only, Direct mode generate MILLEGAL DIRECT ERROR. 


Examples; 100 INPUT “NAME” RS 
LEO INPUT "ADDAESA LINE 1 (NO COMMAS)"; A1S 
420 INPUT “ADORESS LIME 2 (HO COMMAS)" |A2% 


These aro typical elementary input statements, sany to program but subject to 
sorlaun drawbacks, ‘Homa’ will homa the cursor; ‘Steturn' will crash the pro- 
gram; Shift-Siop will attempt to load a new program; the mscreun can bo filed 


Se Me ee ee 


cee tere 


= a 


oe 
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$: BASIC keywords 


with unwanted characters; commas or colons cause som: i 
; e of the atr 
lost. See the notes for cures for these problems. is Sart 


1000 INPUT AAS, Ba, CE ‘REM INPUTS MUST MATCH 
2000 FOR J=O TO 10: INPUT X${J}: NEXT ;:REW INPUT 10 STRINGS ... 
2010 FOR J=0 TO 10: PRINT X$(J): NEXT :REM ... AND CHECE THEM 


Line 1000 expects three inputs. This is a valid response: 
i HELLO! ,-123.45,7.1 
After Return, AAS="HELLO!", BB=-123.45, and C%=7. Integer 
ep .45, =T. assignments 
follow the hormal rules as to range and rounding. -1.2 waka Be samigned ~2 
This response will produce 7EXTRA IGNORED:- : 
‘ans Palani hair ppael 
n is will produce 7REDO FROM START, because of th i 7 
: ras @ type mismatch: 
ne or two entries only will be accepted, if they're valid, and the doubl 
, : : . e@ 
prompt of ?? will be printed on the next Line, awaiting complete input. 
Lines 2000-2010 show how array variables may be used for input too. 


Further examples showing use of (i} String literal, (ii) Keyboard buffer. 


Notes; 


Abbreviated entry: None 
Operation: Hue INPUTH 
ROM entry pofnis: BASICL:$CAZO (91996) BASICZ:SCACL (51905) BASICS: SHAD (48082) 


The following examples show some of the ways in which INPUT can be modifled 
The first four use screen editing characters to produce interesting variations ; 
on INPUT, including positioning on the screen, underlining, and reversed 
text. The fifth is a typical 'crashproofing' routine; sometimes * is used in 
place of upper-case (i.e. shifted) space. The sixth shows how characters may 
be inserted into the keyboard buffer, which is equivalent to keyboard entry 
after the prompt and cursor are printed. They offer the possibility of erasing 
the prompt and ~ as here - automatically entering " at the start of the input 
in order to force acceptance of strings with commas, ete. Where constructions 
like "LDA $8000,X" are common, this is quite useful. The extra " turns off 
quotes mode, soa the screen editing facilities will operate. 


10 INPUT “ [CLR] [DOWN] (DOWN ) [DOWN } [DOHN j [DOWN] [DOWN] [RIGHT] [RIGRT] 
(RIGHT ] (RIGHT) (RIGHT) (RIGHT) (RIGHT ]";X$: PRINT X$ 

20 INPUT “HELLO(DOWN)} [DOWN] [DOWN] [DOWN}(RVS]";X$: PRINT XS 

2 edad {DOWN } (DOWN JTEXT [UP] (LEFT) (LEFT )(LEFT}[LEFT]";X$: PRINT X$ 

mew wewnes (LEFT) [LEPT) (LEFT) {LEFT ) (LE 

{LEFT][LEPT][LEFT])";X$: PRINT X3 s en ee 

50 easel gaalael NAME (USPC } (USPC) (USPC) (LEFT) (LEFT) [LEFT )"; X$: 

60 POKE 158,3: PORE 623,34: POKE 624,34: POKE 625,20: REM 3 ITEMS IN 
KEYBOARD QUEUE, WHICH AHE 2 QUOTES AND A DELETE,(BASIC1:525 & 527ff) 

70 INPUT X$: PRINT X$: REM X$ MAY INCLUD® , AND/OR :. 

{1] See Chapter 4 for methods of foolproofing input using GET. Because 
INPUT can occur with screen scroll, if for instance many wrong entries cause 
the bottom of the screen to be reached, {t's worth checking the result of an 
overflow: use, aay: 10 INPUT " YERY LONG MESSAGE "[2X$/15 PRINT K$/ 
20 GOTO 10. BASIC 4 ia different from BASIC<4, 


[2] When CMD is in force, INPUT “WESSAGE”; M$ will print the st 

device, so that MESSAGE may appcur on a Grintues SeILs BAtk Room ncine 
that INPUT is attempting to get data from u lintener, such asa printer. When 

a file is open like this, the 'Return' crash won't huippen: OPEN 1,Q;INPUTAL,X$ 
for example inputs from a file to the keyboard. POKEing the device aumber : 
location wlth a pxeude-fe nuinher has similar effects: try POKE 3,1 with 
BASIC 1, POKE 14,1 with BASIC 2, or TOKE If, f wlth GASIC 4. ; 


[+] Direct made is prohibited beenuse the buffer which holds eet 
commands it tne same as that in whieh taput characters are een val cane 
however try direct mode: une SYS 51956 X$, SYS 41925 X$, or SYS4H0R0 X$ 
with BASEC 1/2/74. This will attompt to axsiyn X$ to your Input. [t mises the 
tant for direct mode, SYS of the HOM addreqses bulow works exactly Like 
INPUT, oxeept that H will not print a siring; try e.g. SYS4GUG2K5,Y 4,2, 


Token: $95 (133) 


“ 
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NPUT # 


SASIC Input command 

URPOSE: Provides users with an easy method to read back data from a storage 
device, normaily tape or disk. The input which Is read by the CBM is 
processed in the same way 25 INPUT processes it; this means that data sent 
to the storage device by PRINT# will be recovered intact. The formut is 
consistent with that of PRINT# for strings and numerals. which are written 
as individuel ASCIi characters with carriage returns as separators. However 
some characters aren't recognized by INPUT# and are ignored; these include 
the screen editing characters, unless the quote character, CHRS(34), was 
written at the start of the string. Note aiso that 60 characters is the max- 
imum length of a record recoverable with INPUT#. 


Syntax: INPUT#arith.expr. ,var. name ty var. name)(, var. mame] ... 

Aa with PRINT#, a space between the two parts of the keyword’s name causes 
the interpreter to see two tokens instead of one (except in BASIC 1t). The 
arithmetic expression is the logical file number of the input file, and must 
avaluate to 1-255 with rounding down. The comma and at least one subsequent 
variable are also compulsory. No optional string exists, as it dees with INPUT 
since a prompt is out of place when reading from tape, say. 


The data which is read in is processed according to these cules:- 
(i) Alphanumerica are dealt with straightforwardly, and Return, when it is 
read, 1.6, as CHRS(13) or $0D, terminates a record, in exactly the same way 
that the Return key sends data from the keyboard. In an snalogous manner 
commas or colons, if they were not preceded by a quote mark, are treated ag 
separators, and the subdivisions of data which they seperate are all assigned 
thelr own variables. There is no equivalent ta 7EXTRA IGNORED, but none- 
theless data will be lost if an INPUT# statement takes in data te the buffer 
which is subdivided inta more parts than there are variables; this can only : 
happen if commas and/or colons are used carelessly, e-€- with PRINT#1, CHR${44) 
or PRINT#S,CHR$(538). 
til) Most other errors cause the program to crash with FILE DATA ERROR or 
BAD DATA ERROR in BASIC 2. For example, this occurs with INPUT#L, X$ 
when X$=CHR$(32), because leading spaces are ignored. Similarly, when the 
data doesn’t match its asalgned variable, this error occurs. 
(ii) The maximum atring which may be input ts constrained by the input buffer 
to 79 bytes (89 in VIC). BASIC 4 signals this condition with STRING TOO 
LONG ERROR and crashes the program: earlier BASICs hang. 
Mode: Program mode only, Direct mode generates 7ILLEGAL DIRECT ERROR. 
Examples: 10 OPEN 10,2,1,"TEN NAMES"; REM OPEN TAPE FILE PCA WRITING TO CASS . #2 
20 FOR Jei TO 10: INPUT X$: PRINT#LO,X$; NEXT: REM WA{TE TAPE FILE 
30 CLOSE 10: REM CLOSE FILE, 1.2. WRITE FINAL BUFPER OF DATA. 
100 OPEN 5,2,0, TEN NAMES": FOR J=1 TO 10: INPUT#S5,X$: PRINT X$: NEXT 
110 CLOSE 5: REM INPUT@ HAS EPFECT LIKE PRINT#, 50 CLOSE [9 NO PROBLEM 


The above example shows & simple write-then-readback program, omitting tape 
rewind details snd ST checka on INPUT#. The logical file numberuw are arbit- 
rary and different from each other to make things clearer. [INPUT# ly far lene 
trouble than [INPUT to uso, because its date is already formatted ln a Known 


WHY. 5g open 1,0: RRM OPEN PILE #1 TO THY KEYBOARD 


20 OPEN 3,3: REM OPEN FILE #3 TO THE gCREEN 
30 INPUT#1,X$: REM INPUT PROM KEYBOARD 18 SIMILAR, NOT [DENTICAL, TO INPUT 


40 PRINT#I, 23: REM PRINT TO SCHEEN FILE 

60 GOTO 3d 
This noxt example shown how flew can he opened tu the ksyboard and the 
acroan, Heeause an input file (logical fis #1) Js open, the Input ernsh on 
pressing ‘tetuen' alone doesn't happert. A sereon file is useful sometimes If 


CMD jn belng uned: PRINT A Hendy qutpat ta the ecreen only. Input from the 
screen fa similar to norm 


Lanput, ut dee string may wrap round to the next 





A 9p te pe 


aed 
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Abbreviated entry: iN 


5: BASIC keywords 


Toe sete Lente paves in Eo pte line tabie, with 40-column screens 
or 79, this int ith 
30 ENPUT#Z,X$ and add 45 PRINT “LENGTH="; Nab ial a aceai 


3 ut ve 
Io FOR Jal TO20: Tée"RECORD NUMBER" + STKS(3) RIM MAKE UP DATA 
: "+ STK$(J) : REN MARE UP 
Fs binkiab bah ich PRINT DS$ ST: REM WHITE DISK + SHOW BOTH ears © 
: DCLOSE : NEM 10 RECORDS WAITTEN 


deh ae ie FILR",O1 : REM OPEN SAME FILE ON DRIVE 1 FOR READ 
bee Eno £0 0 SNRUTOL 2S :REM READ BACK WITH INPUT# COMMAND 
1015 NEXT: DCLOSE. : MEM PRINT RESULT + STATUSES 


This pair of programs is the BA i 
, Sic 4 disk equivalent of the earl 
gram. Again, ten recnrds are written with PRINT# and read Back with INPUTS 


Notes: 7 
lotes: {1] How INPUT and INPUT# work. The buffer used by INPUT in CBM comp- 


uters starts at $0200, immediately above th 
$0250, This short routine enabled. you to Apacer aca ene 
a iyoinaliy th TO 592: PRINT CHR${PEEK(J});: NEXT * : 
re ES aie ne eas teach kaput chem lines, new and short lines over- 

f : » Ea unk is terminated by a zero i 
ppdledharsk toro abd won't show. When !NPUT or INPUT# is pining an: 
Sharcuren eb 3 put into this buffer. Eventually, carriage return is input 
tlle ld ae eee byte is put in and the buffer parsed by INPUT. 
eae nucecisere col tes separating the buffer: each chunk is assigned 4 variable 
farher Gp heey es are processed in accumulator #1 before being stored 
Bae tet Gould : The lst byte therefore may contain a zero, BASICs 
tables of logical fites. Pina okie pokey bah le ee evesueine tte 

: secondary addresses, so overwriti 
eee oY sited the data were identical) removed the record oF Hee Files 
vii ai icin As Program, Location $1FF holds a comma: this is to ease the 
pala vig c ¥ making each chunk start in the same way, as BASIC i 
with a zero ‘end-of-line' byte. Taking an example from INPUT, we hnny 


have something like this: * 
-07|-08 ~OA |-O0B 


From which AA$, BB and C% are assigned, 


{2] Disk files may sometimes h 
e ave data stored with a L 
: ; y a leading | ~ 
ele end nes of pre-BASIC 4 files written without the ea: 
Gi ae rte C13}; but with PRINT#N,X$; which sends Carriage eetiien 
a line beiow their peal rg dite : idea Dea Rinccrecln ie e 
ed place, put a test- - 
7 TOO TF ABE(gUve io CRN Aecatuaces a st-with-correctlon like this; 
ne-feed is ASCIL 10; when found, X$ ls stripped of its initial. 


Token: $84 (132) 








Oper .f : 
eration: This is similar to INPUT, except that the Input device as specified by 


log le 
eos ile number in first set, then unset, on either side of INPUT. The actual 
eri Boke piex: 4 flag, $0H7 holds 0 to algnify INPUT (#$98 means READ 
haga aie ebay Mug, $037 holds the quetes mode on-off byte; two more. 
i ae ait are used in type matching, hulding reapectively 4$EF or #0 
Ha string eral, and #380 of #0 for Integer/real, With BIT and b " 

Nes aca elaborately nogotlated, ed 


ROM entry points: 


BASIC 1: $CACE (61919) 
BARIC 2: SCAAT (B1a7u) 


a = BASIC 4: $BHA4 (48038) 


*BARIC t's : : pale g any pa Sip ass plo 

dis eG ee extends from $0A-$50. $54 be uand for working storage yuo b 

ih Sastc maa. 80 J=9 TO SU in the correct PAEX loop with BABIC 1 ae 
1, these are, in order, $42,354,352, and $5F. : 
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INSTRING$ 


BASIC string function unavailable directly in CBM BASIC 


PURPOSE: This verslon of INSTRINGS inserts one string within another, without, 
however, overrunning the end of the relpient string, {t is modified from a 
routine by W Maclean, quoted by Jim Butlerfield in CPUCN v2#8, who says 
that this type of routine is useful for ‘manipulating data records in disk 
files and setting up formatted printer or screen outputs’, The routine is 
relocatable; location 0 holds length, ($0) pointer, to the string, 3° USR 
(if any) will have to be repoked. The demonstration program seta up 4 
few adjacent strings in memory; this is a check to ensure that overlap from 
INSTRING$ doesn't corrupt the next string . 


Machine code: 


5: BASIC keywords 


This version is BASIC 2; see appendices for other ROMs. 


Input expression~ Error message if absent, 
Check it’s a string. Error message if note 
Loop inputs LEN of second string into loca- 


io 949 20 9% CC $0350 JSR SCCOP 
lt 851 2090 CC +§0353 JSR $cc90 
$0356 LOY #902 


Check for comma, Error message 1f absent. 
Input expression. Error message {f absent. 
Check it’s numeric. Error message if noc. 
Convert Fl Pt Acc#l tnto tnteger- 

Check that the numeric value does not exceed 
the end of the acting into which it is Co 


17 864 20 FB CD $0360 JSR SCOFS 
1a.) B67 20 9F CC $036} JSR SCCOF 
19 870 20 SE CC $0366 JSR SCC8E 
20 873 20 D2 D6 90369 JSR SD6D2 
2t 876 «618 $036C CLC 

$036D LDA Sil 


ee eee 


23 979 «C5 Ba $036F CMP $88 be ineected. Exit if ic is- 

24 881 BO 1B $0371 BCS SO38E 

25 983 65 89 0373 apc $89 ; Increment the second string pointer by the 
26 g35 65 89 0375 STA $89 5 low byte of the numeric value, ao the 
27 gB7 90 O02 $0377 BCC $0378 . pointer points {natde the string. 


rt] 889 £6 BA $0379 INC $8A 


29 891 AQ OO $0378 LoY #$00 Load a byte from the first string +++ 


30 «893 s«BL OL $037D LDA ($GL),¥ sek 

31 895 91 89 SO37F STA ($89),¥ 5 wee & put it into the second. 

32 897 cB $0381 Int + Increment the position counter t+ 

33 898 98 $0382 TYA 3 Now check that the new value of Y doesn’t 

34 a99 (18 . $0393 CLC . Hy point outside che second string; if ic 

35 900 65 11 $0384 apc $tl H does, some other string wilt be corrupted: 

36 902 cS 68 $0386 CMP $88 

37 904 BO 04 $0348 BCS SOE 

38 906 c4 00 goisa cer $00 ; Chack whather ve’ve now moved evecy byte 

39 908 pO EF gozac «BNE $0370) + of the first string ~ 1f so, exit. a 
40 S10 66D $038E RTS : 


BASIC demonstration: 


O INPUT “MUMBER (ND; N 
1 AGs"AAAAAA": RS2"1239"; B$«" BBBABD" Y$e"ABCDE’: C9s"CC"; 2$-"DDDOHppoODD™ 
2 AQWASS: AB=KBH: Usenet: VHS: CH CH": DSaDFe': REM IN HIMEM 
3 8Y8 826,X$,%9,N: PRINT AS" UXg" UBS UVR VCS" “O$: AEM DISPLAY VALUES 
440 TO 0 
(mp; tine 2 by calculating the ateings, loaves thon unchanged, but In high RAM. 
If thia tan't done - try datating linn @ to avo the effoct - the actual strings 
in line t are changed, #v the lvop in line 4 won't work en aight Se exrpoctad) 
The program run a” it stands gives: 
NUMMER (4)? 9 
AAAAAA 12] BREBBE 1a3y% ¢C DyLUVHDODD 
NUMBER (RD? 2 
AAAAAA 123 SBDDBB ALASE CC ODDVDRDDOD eta: 





| 
| 


1 626 20 #8 CD §033A JSR $cDrs ; Check for comma. Error message if absent. 

2 829 20 9F CC §033D JSR $cc9F ; tnput expression. frror measage if absent. 

3 aj2 20 90 CC $0340 JSR §CC9O Check it’s a string. Error massage if not. 

4 835 AO O2 $0343 LOY #$02 3; Loop inputea LEN of string into location $00, 

5 837 381 44 $0245 LDA ($44),¥ 5 and stores pointer to the atart of string : 
6 839 99 00 00 $0347 STA $0000,T 5 {nto indirect @ocation ($01). i 
? B42 88 $0344 DEY | 
8 843 10 FS $0348 BPL $0345 

9 845 20 P8 cD $0340 JSR ScDrs Check for comma. Error message if absent. 


3 
’ 
+ 
' 
> 
, 
3 
’ 


i} a56 Bl 44 $0358 LDA {$44}, tion $8%, and stores pointer Co start of 
14 958 99 88 00 $035A STA $0088, f accond string in indirect location ($89). 
15 861 88 $035D DEY (This is in the RND work areal. 

16 862 10 FS $035E BRL $0358 
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INT 


BASIC arithmetic function 


5: BASIC keywords 


‘ ts ti argu 29 
¢ td 
PURPOSE Converts the rgum nt into the near est Integer which is less than 


s : F : . 

Me a Staselen ie UIC lenae The argument must be a vatid arithmetic 
pla : : e limit is not the range for integers, but is the range for 
Hetdatet elNriiceisls eee va 1.7 E 38. For this reason the 

= -8) is valid. However, Lt=I 2 
an error, since the result is too large for an intabersvarueles ores 


Modes: Direct and program modes are both valid. 


Examples: 100 PR 
: INT INT(X+.5) : REM ROUNDS TO NEARE 
PHINT INT (1294567.8) ; REM 1234567 Re nga ree Ge, 
PRINT INT (-123.4) : REM -124 
1000 PR= INT(,02+ P*(1+MU/100) 
, ): REM PRICE (PENNIES 
30 IP De> INT(D) GOTO 40 : REM GO BACK FOR RE-INPUT AiR Wale 


Mi : s 
nied paral routines in BASIC use [NT. The first and foucth examples 
prbilahon ple rounding; for commercial use such routines must be more 
fate oxeapla: ares as 1.00 and so on. The principle on which 
reliea is that the entire range from X,000 i 
converted to X by INT. Obviousi Taree al 
x y to round to the nearest b 
not just drop the decimal portion 5 ice ino ce 
: hac t be added, shifti 
to X,500 to X+1.499, so the low are i cine 
X¢1, ' er half are rounded down by INT 
upper half of the range are rounded u i is a: Ged Senin 
\ p. Line 1000 is a simila 
bib ie a price and MU a markup percentage, The value PR aurea 
ee i ag there is a small item (.01) also included, This is often 
aren hen ae this ae occasionally will round down a value 
cessary. [n the illustration, P 

Phy [ F may be 1000 
il seek: outcome of the calculation fs held in floating paint as 1249-8908, 

es the 'wrong' value of 1249, and this may be noticeable. ; , 


The second and third examples a i 
Hert aepagiab ap utah rile ve straightforward examples; the fifth is 


Notes: i i 
ia ia doa A brackets may need to be kept there. Zetler's 
: » f inding the weekday uses INT(Y/4} + INT(C/4 : 
which 1s easily 'simplified' Into the incorrect INT(Y/4 + oa 7 Se. 


{2} ‘INT’ is the same function as ' 
2 s ‘ENTIER' in ALGOL. ' , i= 
nets which rounds negative numbers up. This is cadiealehe tee ane 
(XZ) INT(ABS(X)), which separates out the aign. 


Abbrevisted entry: None 
Token: $BS (181) 


Operation: 
ae ee mromies ta eeca’e Buleen valldnted and put Into floating-point 
i netion'’s objective is to | h 
teaeetned aed eave the accumulator with 
equivalent of the same b i 
ied dag roi errt number, agnin in Ronating-point 
7 plishes thls by converting the 

integer equivalent, th vite resjear ber stolh armerieda 
, then converting this back into fl - 

thers tn alse a iaie on 9 floating-point formnt, 
- entry of the exponent; If 

Pep dl ig deh ponent; this excceds or equals 

ap Ae. carried out. The number (>= gly is too large to hava 


ROM entry points: 
BASIC 1; $DBYR (58222) 


AABIC 3; SDBDA (54280) 
AABIC 4: $CEO2 (52734) 
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rogromming the PET/C8M 


-EFT$ 


ASIC string function 
URPOSE: Extracts @ substring from a string, consisting of the leftmost char- 
acters from the string. This function, in association with MID$ and RIGHTS 
and the string coricatenation operator *¢, is used in text and string- 
processing in BASIC. 
yntax; LEFT S(string expression, arithmetic expression}. The string expression 
must be valid. i.e. made up from string functions and/or literals and/or 
string variebles only. Its length cannot exceed 255. The maximum value 
of the arithinetic expression is 255, Its minimum depends on the ROM: 
BASIC<4 will not accept a value of zero. corresponding to a null character, 
but BASIC 4 will. 
fodes: Direct and progrem modes are both valid. 
ixamples: PRINT LEPTS("RELLO"+"THERE!"",3) : REM RESULT IS BEL 
PRINT LEFT$(°HELLO’+" THERE! “,50}; REM RESULT I8 HELLO THERE! 
10 PRINT LEFTS(X$+" "10);: REM A FORM OF TABC 
3010 PRINT LEFTS(STRS(L)+" "(10);: REM ANOTHER TAB( .., 
3010 PRINT L; LEPT$(SP$, LO-LEN(STRS(L)));* REM... AND ANOTHER! 


LEFT'S is closely related to RIGHTS. Further examples of string manipul- 
ationa are given there. These five lines of code demonstrate some rather 
basic points. The first two direct mode statements show how the function 
works; its parameter is simply applied to the string, which may be any 
expression, and measures off a length from it. Rather than print an error 
message if the original string is not long enough (see the second example) 
the length parameter is not nilowed to exceed the length of the string. 


The final three program lines demonstrate methods of formatting strings 
for output to a printer: this can be & problem when TABC( doesn't work. 
Line 10 shows how X$, a string assumed shorter than 10, can be printed 
and also leave the output pointer waiting et a constant position in spite of 
differences in individual X$s. The first line 3010 uses exactly the same 
conatruction, but applied to a number, The alternative line 3010 achieves 
the same effect, with SP$ defined to be a string of spaces, but it is a less 


elegant construction. 
Notes: [1] Thia diagram should make the o 


xs="(o. a] 1] oJ x] ¥] pT si tr] 8] 1] NG)" 
String position: ray a[ 3] 4) 3| 6 lao [23 [12 13 [14 [18 


PRINT LEFT $(X$,6) printa ORIGIN. These are the six leftmost characters. 
PRINT LEFT S(X$,2)+"GAMI" prints ORIGAMI. 

{2] LEFT S(X$.N) can be repiaced by MIDSCXS.1.N). With BASIC 4 ROMa 
this has no effect, but earlicr HAS(Ce reject LEFTS(X%,N)} when N ig zero. 
The MID$ version is preferabic therefore when older ROMs are used and 
when a null character may be legitimately returned, 


Abbreviated antry: IcF (includes $) . ss Token: $C8 (200) 


Operation: The pointer to the atring, and {ta porumeter, say N in LEFT $(X$.N), 
are recovered from tho stack, where they are pul by normal string function 

processing. ‘Tht longth af the string ie fourm) the pointer polity at it~ 
and conpured with N; the smuller of the two fs taken. t) is punted ante 
the atack, followed by the sinnlier parameter (in the provesa, xX, Y,and A 
are swapped around In a jyte- aaving but confualng way). Finny, the 
routine which LEPTS, RIGHTS and MID$ nil xbare Is dropped into. and the 
new atring Is set up for printing or assignment, : 


peration of this function clear: 


ROM entry points: 


BASIC t: SOASDH (64744) 
BASI{C 2: $DSUA ($4748) 


BASIC 4: $CH3@ (01254) 





Ties 


—) 


ose te 
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LEN 


BASIC arithmetic function 
PURPOSE: Determines the jength of @ string or string expression. 


Syntax: LEN(string ex i i 
N¢ pression}. This is an arithmetic function of a stri 
Leech in iad ti be valid; it can consist only of arses 
25 ring functions concatenated by +. Its maximum rmissi 
il dy gs fe characters. If spaces are included when using BheiCoi: tor 
il nce N("D"), an array LEC) will be assumed, and a ?TYPE MISMATCH 
ROR generated whenever the code is encountered. 


Modes: Direct and program modes are both valid. 


Examples: PRINT LEN("BBLLO”) : BEM RESULT 19 © 
X$=" SAILOR"; PRINT LEN ("HELLO"+K$}+3 : REM RESULT IS 85 


330 FOR J#1 TO 16 
340 PRINT SPC(19 - LEN(MSG$(J))/2)>; MSG 
aac ex? ) i $(J)> 


IF LENCIN$)<>L THEN PRINT "*¢* MUST BE" L “DIGITS” 


250 X9=" *&e" ; REM LIST OF SPECTAL CODES TO BE CHECKED ... 
260 FOR Jal TO LEN(X$) : REM NOTE THAT THE LIST IN LINE 250 CAN BE 
270 «IF G$=MID9(X$,J,1) THEN RETURN: REM CHANGED; THIS ROUTLNE WILL 
480 WEIT: PRINT "NOT RECOGNISED": AEM STILL WORE CORRECTLY. 


The first two examples in our illustrative batch sre straigh w i 

mode arithmetic calculations. The first simply measures n hephaeape of ons 
acters in the string; the answer ts obviously five. The second is more complex 
and ahows how LEN, being an arithmetic function, can be used as part of ai 
arithmetic expression, Again the answer is obvious - the combined strin 
"HELLO SAILOR" is 12 characters long; 12+3 is 15. . 


The short routine in lines 330 - 350 is a formatting rout i i 

ten strings held as MS$(1} to MS$(9) one after he epi net) igh i eas 
screen (change the parameter to 39 for an 80-column screen). It does this 

by printing sufficient spaces to print half the string before the midpoint of 
the screenline. The other half of the line is therefore printed symmetrically. 


The next line of code is a simplified fra i idati 
F: gment of an input validati ti 
which tests the length of an input string against its correct wauer er 


Finally, llnea 250 & 260 show between them how L i 

‘ ; £N can assist in soft-codi 
and make @ program more easily modifiable. Had the loop variable ‘in tine 266 
been 4, program maintenance would have been a little harder. 


Notes: (1) LEN cannot return ‘outsi 
i ; a value outside the range 0-255 (see diagram). Th 
Jength isn't actually measured; only the parameter in taken, and rents . 
can result from this, e.g. when CHR${0)s are concatenated onto a atring 
or the parameters are aitered by direct poking. . 


Abbreviated entry; None Token: 803 (95) 


Operation: The ROM has onl 

: b y one subroutine followed by a jump. The sub 

Nercg 7 shared by ASC and VAL) sets pointers to the sirlng and Talents 
; ength Into both A and ¥. This part has been slightly rewritten in BASIC 

. The mode fing is changed from string to numeric; thle la necesssry to 

avold 7TYPR MISMATCIL ERRORN. Now a Sixed-to-flouting polnt conversion 
routine Is jumped to; this ono la in POS, which puta zero into A and in 
effoct converta the iength in ¥ only Into floating-point. ; 


ROW eneey. Golhta: hang wamx]eewcte] porren| o | | 


BABIC 1; SD064 (54844) 
BASIC 2: $0054 (64870) 
BASIC 4; §CHB2 (81378) 


i “heen awe = ; " . wary ES See WT eS 
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LET 
BASIC command 


PURPOSE: Assigns a value or a string to a variable. The variable's name causes 
an integer, real number, or string to be allowed by the assignment. 
If the types don’t match - if a variable with a string nome is assigned a number 
or a numeric variable assigned a string - then 7TYPE MISMATCH ERROR is 
printed. Interconversions between integers and reals are allowed, subject to 
the condition that integers be within the range -32768 to +32767. 


Syntax: LET is never needed with CBM BASIC. If the first item in any statement is 
not a token, LET is assumed by default; the parsing process looks for a name, 
the '=' sign, and a matching arithmetic or string expression. With square 
brackets representing the optional command, the syntax is:- 

{LET] Real variable name = arithmetic or integer expression, or 

[LET] Integer variable name =arithmetic or integer expression, or 

[LET] String variable name =string expression. 

Variables can be either simple variables (e.g. X,C%,A1$) or subscripted 
variables like A(7),JK%$(100),M$(Z). If the variable doesn't yet exist, it is 
set up in one of the two RAM areas used for the purpose. Subscripted 
variables are put into the second of these areas, with dimension(s) set to the 
default value of i0, if a prior DIM statement hasn't been used. An integer 
variable ia assigned the rounded-down value of the arithmetic expression on 
the right of '=', but if the value is too extreme ?ILLEGAL QUANTITY ERROR 


results, 
Modes: Direct and program modes are both valid. 


Examples; LET B«45056; LET RQ=.005: REN SAME AS B=45054:RQ=.005 
LET Q%0Q/256: L&T A1%=12.9: LET BX&=10000; REM SAME AS Q$2Q/256 ETC. 
LET S$="BCFGHPQSU": LET DO$="WRITE”: REM OR S$="SCFGHPQSU" :DOS="WRITE" 


100 FOR Jal TO 50: READ X$; LET ¥$(J)=X$; NEXT 
142 IF JDLEN(JD$) THEN LET JD=0 


The three direct-mode examples show real, integer, and string assignments. 
Note that the expressions assigned to integer variables need not themselves be 
integral, but wil! be rounded down. A1l% takes the value 12, and Q3 is set equal 
to the higher byte of Q, assuming Q is in the range 0-65595. The fourth line 

is a composite LET statement which assigns fifty subscripted variables with 
strings read from data statements. As with all the other examples, LET may be 
omitted. Finally, we have a conditional assignment (taken from @ decimal point 
procesaing routine}. Note [5] enfarges upon this topic. 


Notes: [1] Some BASICs require LET in their assignment statements. 


[2] The assignment routine can be called in machine-code, and used to aet up 
special user-defined variables. See VARPTR for en explicit example. 


[3] Varlablea can be assigned and re-assigned with complete freedom. Thia 
can cause problems: a varinbie may be changed or reused without its previous 
use dbelng remembered. This in particularly a hazard with subroutines, and is 
the reason that tables of variables ought to he kept with large programa, There 
are computer languages which possesa both ‘local’ and ‘global’ variables: FOR- 
TRAN and PASCAL da; COBOL doesn’t. Aa an fllustratlon of the type of trap 
which may occur, consider this subroutine, which prints the value of Lava 
‘hexadecimal number, so that L=52000:GOSUB 600 priata $CB20: 


800 LoL /4006 : PORS=1T04; L4uL; PHINTCHAS (46+L%- (L499) *7); :Letes(L-LS) MEAT: 
RETURN 
Tho subroutine uses, in addition to L, variables J and L&. The valuos of cach 


of these are changed by the aubroutine. Suppone a tubte of hexadeckmil values 
la wanted corresponding to 52000 - 32020. This loop: FOR h*$2000 TO 62020:L=f: 


GOSUB 600; NEXT will work correctly. This one: #0R £=63000 TO 62020; GOSvEaOO: 


WEXT will not, elnceo L la changed by tha subroutine, 





TO AE eee ETN OY RII. = 


Scr 


Programming the PET /CBM ~a5~ 


5: BASIC keywords 
(4) String Assignments. String variabies hold their strings in two distinct ways 


and this peculiarity of Microsoft BASIC needs to be borne in mind tn several 
circumstances, the most common being the situation when a program ts loaded 
from within another program, but uses the first program's variables. (The LOAD 


command of course is speciatiy designed to permit this in CBM's BASIC). 


10 REM *** DEMONSTRATION PROGRAM TO SHOW VARIABLE SHARING #** 
20 A$="HELLO": B4="STRING EXPRESSION'+"" 
30 LOAD “2ND PROGRAX” 


10 REM 2ND PROGRAM 
20 PRINT "A$=" AS 
30 PRINT "B$=" BS ; AEM ABCDEFGHI JKLMNOPQRSTUVWXYZ 


These demonstration programs (written for tape ~- the disk version is similar) 
show the problem. SAVE program 1 on tape, then SAVE "2ND PROGRAM", 
Rewind and LOAD the run program 1. This puts two string variables after the 
program, AS$and BS. But (see diagram) the pointers to A$ point within the area 
which program 1 occupied; in fact they point to the position in memory where 
*HELLO" originally started. The second program therefore prints A$ as a string 
of the correct length but starting somewhere in the REM statement in line 30. 
The exact position depends on the number of spaces inserted into the programs. 
Variable B$,on the other hand, appears correctly as "STRING EXPRESSION". 
This is so because all eveiuoted strings need to be processed, and have to be 
stored in the next available space in RAM. (Again, see the diagram}. Chapter 

2 has a longer explanation of this and similar phenomena. 


[procnaM 10 Jas as~ BS STRING] 


Foe Ne 
as] Bs[ STRING | 


(5] When LET Is not used, it becomes easy to forget the distinction between 
's' ag an assignment, and '=' as @ comparison operator. The statement: 

IP I=Q0 THEN 1212345 or IF X=0 THEN LET X=12345 
uses '=' in both senses; the first use does not, obviously. set X=-0. When LET 
ig compulsory, the distinction is retained, The language 'C' uses ‘==' as its 
assignment operator. One practicul effect of this occurs where dummy variables 
are set up at the start of a program. This statement: A=B-C=D-€ looks as if 
it will initialise these five variables in the correct order; in fact, the statement 
is parsed A=(B=C=D:E), and the bracketed expression evaluated. Only A is get 
Up, so the hoped-for speed improvement may not materialise. Rather confusingly 
thls Isn't true of arrays. A=B=C=D(5) sets up A and D with the defautt dimen- 
sion of 10 Lf lt doesn't exist already. 


ZNO PROGRAM 





Abbreviated entry: LE (or nothing) 
Token: $88 (136) 
Operation: Varlables are assigned tke this: first, tha variable is sought In RAM and 


ROM 


get up if lt does not yet exist. (Thi« can be « longish operation if arraya have 
to be moved to accommodate simple variables). [ta locatlon lu saved, Now, the 
token for '=' ($B2} ls checked; If something clase la present, 9SYNTAX ERROR 
Is printed. Two variable-type flange are snved on the stack; these were set by 
the original search routine, Location 7 holds #0 if the variable was numeric, 
4FF Uf it wana string, and § holds #40 for an Integer, #0) for a renk variable, 
Now the expresslon [a evaluated; u general-purpose routine exists for thia 
Purposc. The result la checked for type maich with the verlable name, giving 
?TYPE MISMATCH ERROR when approprinte. Finally, the routing branches to 
three places, to process integers, reals, and strings respectively, A special 
check for TI$ ia included In the string processing. All tho KONa« are slmilar, 
but BASIC 4 aas extra string processing to handle lta complement of pointers, 


entry points: 


BABIC 1: $CHOD (51357) | 
BASIC 2: $CHAD (51373) 
BASIC 4: $nD90 (47408) 


A ROTEEIRE oe : 
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LIST 


BASIC system command 
PURPOSE: Displays part or alt of a BASIC program In memory in a readable form. 


Syntax: LIST LIST tinenumber LIST linenumber-linenumber 
LIST - linenumber and LIST linenumber - are all accepted. LIST 0 ls 
interpreted in the same way as LIST. The actual tinenumbers need not exist 
in the program to be specified as parameters. 


Modes: Direct and program modes are both valid. In program mode, however, 
this command will stop the program when the lines have been ilsted. 


Examples: LIST :REM LISTS ENTIRE PROGRAM 
LIST 1000 :REM LISTS LINE 1000 (IF IT EXISTS) ONLY 
LIST 60000- :REM LISTS EVERYTHING ON AND AFTER 60000 
LIST 70-200 :REM LISTS ALL LINES FROM 70 TO 200 INCLUSIVE 


S55 PRINT “Mal INSTRUCTIONS “ 

3560 PRINT “DaRYSe PUTS TRACE ON/OFF ON 

4390 PRINTLOS$RS$"DISK TYPE3 = "DT$: PRINT "C2HECK HISTORY" 
57055 print "+eqcgedooeneqnand Lcocegenecatodd LegGdcdds .”; 


20000 LIST 400: REM LINE 400 HOLDS DATA RELEVANT TO THE PROGRAM 


The first four examples illustrate, with comments, various permutations of 
this command. Often the output will appear on the screen. When this is 
the case, screen scrolling may be slowed with the RVS key, or, with the 
8032's revised keyboard, <-. BASIC 4 also has a pause feature, activated 
by either : or *, and cancelled by any of a number of keys. 


LIST can be made to print to other peripherals. If it is directed to a 
printer, typically by OPEN 4,4: CMD 4: LIST a hardcopy will be generated 
on paper. [t can also print to a cassette or disk file; In this case the file 
contains the program as fisted, with PRINT for instance stored in 5 bytes 
Inatead of the usual tokenised single byte. The three examples of hardcopy 
program listings show the output produced by a Commodore printer, which 
is very slmilar to the way the screen displays it, although some of the dot 
patterns are not identical. Non-Commadore printers don't usually have the 
special characters of CBM's set. and in some cases, for instance daisywheel 
printers, cau't have. The two lines 4390 and 57055 are typical examples of 
this sort of thing. Most of the listing is intelligible, but strings within 
quotes may produce anomalies, Line 4390 includes some RVSOFT characters 
which obviousty are there to help with the screen appearance. Line 57055 
holda a string of graphica characters which in fact are the top line of 4 
box used In inputting duta. Although tirenome, thls ls not usually much of 
&@ problem, Commodore tend to view all this as a reason for buying only 
CBM printers, 


The last example shows LIST in program mode. It acts rather like STOP, 
except that CONT won't work, but it also ilsts the lines requested, There 
is an application of thix in the relocatable loaders for LIST {q.v.). 

Notes: (1] REM. quotes, and POKEs. Shifted charactera after REM, snioas enclosed 
in quotes, ure Interpreted as tokens, and priatud out In thelr expanded 
forma, Soe the notes under REM on this subject. REM Ia also capable of 
holding carrigge returns, form fecds, screen clears and wo forth, und these 
arc sometimes used to improve thy herdcopy appesrunce or provide a rusli- 
mentary UNLIST. LIST does not provide a one-te-ane conversion of program 
information Into listing. Hy POKEing, llnes can he generated which 1i8ST 
apparently perfectly but produce 75¥YNTAX ERROK un running. Ath appendix 
on internal storage of BASIC glvea dotuila, Strings can be maile to lat oddly 
by inserting unusual charactors: For Instance, Dil keya can muke pnarta of 
a Ilsting Invisible, on the serean at least: 10 7"GO AWAY" can be edited by 
moving the cursor back over the second quote, Inserting eight apaces with 
the Inncrt key, putting in eight deletes (which appear as revorse T) and 
eraning the final quote. This liate an 10 PRINT, 


= whee 


SA i ieee 


: 
} 
: 


Programming the P&T /CBM -&7~ 


$5: BASIC keywords 


{2] LIST ts upward compatible, but not downward com 

’ patible, between CB 
BASICs, BASIC 4 disk commands (CONCAT, DOPEN, etc} don't exist as a 
keywords, and therefore can't be listed, om earlier ROMs. And BASIC 1 
cannot list GO TO (with a space) since it lacks the GO token. 


(3] BASIC 1 fist has a bug, corrected in later ROMs 

, » which causes @ tin 
of apparent length > 255 to list in an infinite loop. If a Link address is : 
faulty for some reason - perhaps a bad load ~ there is no way to stop the 
loop apart from switching off or using some hardware reset. Lines like: 


49087 SIN SIN SIN SIN SIN SIN SIM SIN SIN SIN SIN SIN .... 
ABB ID FEE HFE HEP OHEHEEEEEE DER EEEEAPEEEERDEEEEO ERED L, 


manifest an analogous bug; perhaps the end of program b 

changed, so LIST continues past the end. Tha ling of mile te an aera 
to interpret a collection of SBFs in memory. ($BF=191, and 191 + 191*256= 
49087). The Hne of plusses is a similar effect, but this time is caused by 
ag, memory, probably left from switchon. ($AA=170, and 170 + 170*256= 


[4] Curiosity seekers might like to note the following: 
i. O LIST is the shortest self-replicating program (unless, as once 
suggested in a letter to'Byte’, the ‘null program’ is permitted). 
fi. The longest listable valid line is a five digit linenumber followed 
by 251 RESTOREs or CATALOGas, depending on the ROM version. 


[5] LIST happens to be a relatively compact command in ROM, and i i 
easy to move into RAM and modify. The TRACE routine printed aseuhore 
and relocating loaders for user~defined LIST show this, Other modifications 
include list routines which scroll down the screen fe.g, in 'Disk-o-Pro') 
lower-case listings for CBM printers which print a cursor down after each 
rad rae ane ee : priate single characters into more readable 
. rol characters, pi, and tokens correspondi 
of upgraded ROMs are likely to be useful, so that [HOME}, fee e te 
and DOPEN replace nonsense characters, blanks, 7SYNTAX ERROR. Yet 
enter possibility is the subatitution of graphics charactera by their 
persis equivalent; programs using graphics are difficult to enter from 
: rdcopy by the keyboard, because they are printed in a run-together 
‘orm which ts painful to read. The only other programs on these 
oe that I'm aware of are by Gregory Yob; see e.g. Printout, April ‘81 
ime with comments. The article is a reprint from ‘Creative Comp- 
Abbreviated entry: II 
Token: $98 (155) 


Operation: This routine uses man 
: y zero page locations; this Is 
& Program can’t CONT if LIST ts used from within {t. Aeothee lithe he 
Hiei address to BASIC Is pulled from the stack. The first thing to happen 
lia the vaildation: ASCII numbers, -, or end-of-statement/ end-of-tine are 
Permitted, If the syntax was correct, the BASIC oddressea are pulled dy 
omit PLA and the Mnenumber limits wet, defauits being $0000 and $l FEE at 
i 8 ands of the range. Now thore is the start of a loop to print a new 
Ine: it tests the STOP key, prints carriage return-iine feed, checka the 
ere ine against the upper Umit, and (if it's still in the loop!) prints 
ie Inenumber. Sow a suvcond loop sturts; this one processcs Individual 
i Oracters . Lf It haa @ quote charactor ($22), It reversas its quotes 
ie If it fInda a zero, it uses the Unk addresa to loop to tha next line 
kee exit, when the link {4 0. I¢ printw the character, unless it isn 
tonn : end the quotes hag Is off, and W fxn't pi; ia thia cnso, yot another 
faa fs entered and the Nth token i4 turned into the Nth reserved word by 
Ping unt N-1 high bytes of the reserved worda table have Pasxed, : 


KOM entry pointe: 


AASIC 1: BCSAR (80400) 
BASIC 2: @CDRS (60819) 
BASIC 4: gn630 (46440) 
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63499 REM ©** LISTING ROUTINE INCLUDING CURSOR CONTROL CHARACTERS “** 

69500 Awl095: Be2356: GOSUB 63600: INPUT “LIST FROM, TO"; F,T: INPUT "TITLE" ; TS 

83501 INPUT "LINES PER PAGE’ ;LP; INPUT MAX. CHRS.PER PRINTED LINE’: C#; OPEN4, 4: 
cub4,; 

63502 PPePP+1; IF PP>LP THEN PP=<1: PRINT CHRS(12): REM FORM FEED 

63503 L«PEEK (A+2)+B*PZEK(A+3);: X=PBREE(A)+B*PEEK (A+): Q=0: IF I=0 OR Lot THEN 
PRINT#4,;; CLOSE4: END 

63504 IF K<P THEN Axx: GOTO 63503; REM LOOP FENDS LOWER LINE NUMBER, L 

63505 IF PP=<i THEN N=Nel: PRINT TS ” PAGE" N: REM TITLE & PAGE 

63506 PRINT RIGHT$(" ‘*STR$(L),5)" "5: COx6: REM CHARACTER COUNT=6 SO FAR 

63507 FOR £2A+4 TO A+93: PxPEEK(t) + REM LOOP TO PROCESS CHARACTERS 


63508 IF CC>CM~7 THEN PAINT: PRINT * "s+ REM CHARACTER COUNT=6 AGAIN 
REM END OF LINE ENCOUNTERED 


83809 If P= THEN PRINT: A=K: GOTO 63502: 

63810 IF P=34 THEN Q=NOT Q: REM REVERSE QUOTE FLAG 
€3520 IF Q THEN GOSUB 63700: NEXT: REW INSIDE QUOTES 

63530 IF NOT Q AND P>127 THEN PRINT T$(P-227);; CC=CC+CC%K(P-127): NEXT 

83540 PRINT CHRS(P);: CC=CC+1: NEXT: REM PRINT ORDLNARY CHARACTER 
63600 DATA ©**, END, FOR, NEXT, DATA, INPUTA, INPUT ,DiM, READ, LET, GOTO »RUN, IF, RESTORE 
63601 DATA GCOSUB, RETURN, REM, STOP,ON, WALT LOAD SAVE, VERIFY, DEF, POKE, PRINT#, PRINT 
63602 DATA CONT, LIST, CLR, CMD, SYS, OPEN, CLOSE GET, NEW, TAB( ,TO,FN,SPC(, THEN, NOT 
63603 DATA STEP,+,-,*,/,4,AND,OR,>,=,< ,SGN, INT, ABS ,USH, FRE, POS ,SQR,RND, LOG 
63604 DATA EXP,COS,S{N,TAN,ATN, PEER, LEN, STR$, ¥AL,ASC,CHR$, LEFTS RIGHTS, HIDS 
63605 DATA GO,CONCAT, DOPEN, OCLOSE , RECORD, HEADER ,COLLECT, BACKUP ,COPY , APPEND 
83606 DATA DSAVE,DLOAD,CATALOG, AENAME , SCRATCH , DIRECTORY 

83608 FOR E=1 TO 9E9: READ X$: IF X$<>#""" THEN NEXT: REM MAKES RELOCATABLE 


63620 DATA 3,3,4,4,6,5,3,4,3,4,3,2,7,5,6,3,4,2,4,4,4,6,5,4,6,9,4,4,3,9,3,4 
83630 DATA 5.3,3,4.2,2,4,4,3,4,2,1,1,2,1,5,2, 2,61, 3,3,3,3,3.3,3,3,3,5,3,9,3,3 
63640 DATA 4,3,4,3,3,4,5,6,4,2,8,5,6,6,6,7,6,4.6,5,5,7,6,7, 9:REM KEYWORD LENGTHS 
63650 DIM CCZ(128): FOR M=1 TO 91: READ CCB(K): NEXT: RETURN 


63700 IF Pat? THEN PRINT "[OGWN]";; CC@CC+6: RETURN 

63702 IF P=18 THEN PRINT “{RYS]";: CC=CC+5: RETURN 

83704 IF Pol® THEN PRINT "[HOME)";: CC=CC+6: RETURN 

839706 If Px29 THEN PRINT "{RIGHT]"; :CC=CCe7: RETURN 

63708 IF P=LA4STHEN PRINT “[UP]";:  CC=CC+4: RETURN 

63710 IF P=l46THEN PRINT "(RVOPF]"; ;CC=CC+7: RETURN 

63712 IF P2147THEN PRINT "(CLEAR)", :CCaCC+7: RETURN 

63714 IF PelS7THEN PRINT "(LEFT)"; CC=CC+6: RETURN 

63718 IF P=255THEN PRINT “[PTI];: CCsCC+4: RETURN 

€3750 RETURN 

This list routine is written as an appendabie subroutine. It searches only for 
those charactera within quotes, although this feature can be rewritten if thia is 
felt important. Any BASIC program can be jisted with any ROM using this. The 


comments make It, 1 hope, fairly self-explanatory. 


RUN 63500 will ask for the linenumbers between which to list, 
d the maximum fine length on printing. I have asaumed the 
he correct postion on receiving farm-feed, Some printers 
feed when the end of line is printed: this is the rationale 
) of the characters on the line ao 
hon BASIC. Details of these are 


of lines per page, an 
printer will move to ¢ 
don't automatically tine 
behind the process of keeping count (with CC 
far. Machine-code routines run much funter t 
prosented clscwhere in this text; see section | 


Varinblca: Ascurrent link nddrens; Xslink add 


enotes the end of the progrom. 
and P the ASCIL value of the character belnag 


a title, the number 


3.4.2 In Chapter 13, 
ress of next fine, and if zero 


L is the current lincnhumber, K a loop variable, 


processed, of rimply the value, in 


the case of a token. Q is the quotes Flagi with eneh new Line St in reset to 9, 
CC is the count of characters printed on the 
permitted number. When a line overflows to a 
In line €3508. 





eurrent line; CMAX the largest 


new ilne, it in iiset by @ spacer 


| 
| 
| 
: 
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LOAD 


BASIC system command 


5: BASIC keywords 


PUR : 
eae tleeh sd . stored memory dump to be reloaded into RAM from external 
Notesuvay bees ce bipiorncd this will be a program In BASIC; it might 
ine code, a dump of the VOU ser r i i 
Stored variabies, or any other set of conti dds een 
’ tiguous RAM addr: 
Any of these less common forma of LO .‘D fai stasenigue, 
1 AD may require special t i 
Prevent the CBM attempting to process the data i if it wees BASIC. . 


$ : pe i 
dag Fap hes this syntax: _LOAD (string exp. [,arith.exp. [,arith.exp.]]} 
allies Parameters are optional, because there is no ambiguity with tape in 7 
ae ih tee ll es program, The first is the program name, the second 
erro num Ore and the third the secondary addréss. The secondary 
herbed yer effect whatever on LOAD; it is only possible to include it 
pach sarah ard are mie. ame ain routine, In all ROMs these para- 
mull strin i 
progran OA dianntiS aL Gil foe (of length 0} and device #1, so the first 
sk has slightly different syntax: the strin i 
roar clghieny and its drive number is canis ira 
a ¢ string expressions are processed diffe i 
re rently: 
path Mid jth bea Bb ship Need match thase on tape, = EOAD VHES lenis 
; X - whichever is first - but rejects HIGHRES and ‘" 
cig pm a Sopnas cate, matching system in which every char- 
e given, unfess an asterisk ia sent, i 
tase any subsequent characters are i i etn Gace 
J Permitted, as with the ta ; 
one or more question marks appear in the stri apne 
to be present, but don't car i i FRU LOAD THETE Blac he sce 
» @ whet it ts. Thus, LOAD "HE*" 
effect as the tape command abo t iota toe a cteee 
ve; it searches both disk drt 
ram with a name that fit ipti m ewe 
REC bat cee 4 its description. LOAD "0:HE???°",9 will load 


SDA ones ti eH een certain 'toolkit'-type ROMs, has the 
ee r disk losds. Also, CBM's monitor h 
fal e oi) n i] aa a ] 
ene cis aie ae: ,01 and .L "O:NAME",08 for tape loading from eee 
Hele aka s tive 0 respectively, After loading, control returna to th: 
rr esc routines ere not treated aa BASIC but as machine code ; 


Modes: Dir. 

: ect and program modes are both valid 

aia eae . Their effects, however, are 
aioe arly CBM manuals include a flowchart which explaina how they 
Direct Mode: messages ar 

: £' e printed to the screen; when the LOAD - 

reed Program ig ready to RUN, LIST, and 80 on; It displaces ei 
a dear gb Anyone ualng a CBM is familiar with this. The sequence 
ov messages appears like this, where square brackets indicate th 
ptional program name allowed by tape loud syntax: : 


Tape: LOAD (“PROGRAM" (,1 or 2}] Disk; LOAD “0 or 1:PROGRAM",8 
_ PLAY ON TAPE #1 or 3 BRARCHING POR PROGRAM. 
SEARCHING [FOR PROORAM] ator ar 
POUND OTHER PROGRAM ... : 

POUND [PROGRAM } 
LOADING [PROGRAM] 
READY. 


I + 
ry ool orice Non axsumad that the named program [ile does actually exint: 
map i ls bon apts reer Soha appear, or, with tape, the recorder 
been weition (abel: end of the tape (when no end-of-tapa hoader haa 
iecbitsan apimcraves iin GG baell Gad Se me tee ee 
big daldgear-aia ceaice r a ond runs the now program, ratsinin 
program's variablos, subject to H 5, 
Chalning many short programs laa relic of the ate PTs. een 
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Examp! 


Notes: 


Abbreviated entry: [0 


5: BASIC keywords 


LOAD REM LOADS FIRST PROGRAM POUND ON TAPE #1 
LOAD “CALCS" ;REM SEARCHES CASSETTE #1 FOR CALCS, CALCS COPY, ... 
LOAD "PROG",2 :REM SEARCHES CASSETTE #2 FOR PROG, PROGA, PROGRAM,... 


LOAD "*"".6 :REM LOADS FIRST PROGRAM ON DEFAULT DRIVE 0 

LOAD "1:4",8 REM LOADS FERST PROGRAM FROM DRIVE 1 

LOAD "0: ASSEM®",@:REM LOADS ASSEM, ASSEMBLER,... FROM DRIVE 0 

LOAD 19,8 (REM X$ INTERPRETED AS STRING WITH PARAMETER & NAME 
LOAD "HEL?*", 8 REM LOADS HELLO, HELP, OR WHICHEVER IS FIRST 


10060 PRINT “PLEASE WAIT.,.": LOAD “NBXT"; REM PROGRAM LOADS “NEIT” 
1235 LOAD "0:ANALYSE",@:REM “ANALYSE” IS NOW LOADED AND RUN. 


The above examples are, ! hope, self-explanatory. With any input/output 
operation, there is a chance of error; °FILE NOT FOUND and "DEVICE NOT 
PRESENT are two 'fatal' errors which will stop BASIC. Other possible load 
errors include (with disk) ?FILE TYPE MISMATCH and (with tape) 7LOAD 
ERROR. Checking DS$ (disk error message) and ST respectively will show 
up errors. [n the case of tape, ST is tested for only one bit after a LOAD, 
ao a checksum error may show up in ST, but not be reported by LOAD. 


{1} Loading from BASIC. This is perfectly successful provided that: 
(i) The newly loaded program is not /onger than the older one, and 
Gi) The new program doesn't use function definitiong or non-computed 
strings from the old program. All of its other variables may be taken over 
with unchanged values; these need to be redefined. This pair of short 
programs demonstrates the use of chaining programs with LOAD; this ls a 
tape version: 10 AEM THIS (LONGER) PROGRAM SETS VALUES, LOADS PRINT PROG. 
20 Awl: BR=2:C$2"39": DS="4"4"": DEF FN B(X)35: FCO) +8 
30 LOAD “NEXT PROGRAM" : REM ‘END’ IS AUTOMATIC 
Save thia first, then save, as "NEXT PROGRAM", this: 
10 PRINT A,B%,C$,D$,FN E(O},F (0) 
Rewind,LOAD and RUN. The earlier program sets up variables with their 
values, then toads the second. This is automatically run, without resetting 
the variables, in effect performing GOTO the earliest linenumber. You will 
see that all the variables still exist, except C$ and FN E. See Chapter 2 
for the reasons: they are in fact falriy atraightforward. 


{2] OLD at the start of a newly-loaded program will enable it to run correctly, 
irrespective of the length of the loading program, but variables’ values are fost. 


{3] A cassette cannot detect if ‘Record iu pressed with ‘Play’. If it is, the 
tape will not LOAD, but be erased as long as the machine contlnues. 


[4] Automatic RUN routines on load can be written for both tape and disk; 
pee Chapter 14, LOAD can be relocated into RAM, so that non-standard 
loadera can be written, One very usefii! ROM routine Is the load routine 
which is used by both LOAD and the monitor'a .L and omitn all the resetting 
of BASIC, In this way, machine-code or a screen dump or whatever can be 
loaded from within BASIC, leaving BASIC running. Compu/think diska have 
thla avaliable aa an option, with syntax $L;Drive, "Name”. With CBM equip- 
ment the following are the relevant locations: 

$D4 holds device number; $01 holds iength of string parameter; if this ty 
non-zero, (SDA) points to Its start, (BASIC 1: SFI, $EE, and ($F9}). Aliso 
the load/verify flag must be set to 0, for toad: this ia 39D (BASIC £: $0205}. 
Finally, calf the second LOAD routine listed below, Example: Io BASIC 4, 
PORE 167,0: POKE 200,0: POKE 212,1: BYS 62294 Loads next program on tupe #1. 


Tokan: $93 (147) 


les: 


Operation: The princ!pal load routine has two parts, one for devices It and 2 (tapes), 


ROM entry points: 


tho other for IKEE devices. The JERE routine takes In 2 characters whiloh it 
presumes to be the start addreas; sudsequent bytes Are atorad there and ate 
subsequent locations, A separate end addrena in not stored, LOAD itself ante 
the load flag, checks the parnmeters, and saves the present pointera before it 
calla the load routing; afterwards It checks ST then cold or warm starts. 


LOAD Ia a "kernel? command; Its jump oddrese le SFFDS. 


BASIC1: 07348 /9F309 BABICZ; BF3C2 /47322 ARICA: $F401 /4F 56 


age yom feTeD errant rer “arp: = 


eee 
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LOG 


BASIC arithmetic function 
PURPOSE: Computes the logarithm to base @ of any positive arithmetic expression, 


ft may be positive, zero, or negative. This function Is the converse of EXP. 


Syntax: LOG{arithmetic expression), Negative or zero arguments will cause an 


ILLEGAL QUANTITY ERROR. There is no upper timit on the ar 
. gument except 
that imposed by the floating-point evaluation of the expression. : 


Modes: Direct and program modes are both valld. 


Examples: 


PRINT LOG(10) 

PRINT LOG(2.7162818) 
PRINT LOG(X)*. 434294484 
PRINT LOG(Z)*1. 44269504 


; REM ABOUT 2.3026 

; REM ABOUT tf 

: REM LOG OF X TO BASE 10 

i. REM LOG OF X TO BASE 2 

PRINT LOGCEXP(N)) : REM PRINTS W {POSSIBLY WITH ROUND ERROR) 
PRINT BXP( LOG(A}+LOG(B) ) : REM PRINTS PRODUCT A*B 

DEP FR P(A}=TEN-INT (LOG( IMT{ABS (A) }+CINT(ABS (A) ) 20) ) *LT) 


The two first examples show straightforward calculations. using this function. 
A logarithm is a transformation that converts multiplicative relations (and 
division} into additive relations (and subtraction), The logarithm of ratios is 
constant; the logarithm of 1 is zero, since multiplying or dividing by 1 has 
No effect on a number, Slide-rules have their sides marked out logarithmic- 
ally. These facts are illustrated in various ways in the examples. The last- 
but-one shows the transformation from a multiplication inte an addition, and 
the use of EXP to find the antilogarithm. Generally, this function is used in 
Statistical and scientific work, either analytically, because its algebraic 
Properties are known, or simply to perfarm calculations in which very large 
humbers are combined to give a reasonably-sized result; this sort of thing 
can happen in statistics. 


The final example shows a tess desirable application of LOG; the function 
definition is part of a rounding routine, to be used in a business program, 
The rationale ig that (for example) the logarithm to base 10 of numbers from 
100-999.99 ctarts with 2; the iogarithm of i000-9999.99 starts with 3; and so 
brid suggesting that a decimal point can be positloned after taking the logar- 
thm of a computed value. Unfortunately, this routine itself ls subject to a 
Founding error; it is possible that 999.9999 may emerge aa 100.006, a rather 
large error, : 


Abbreviated entry: None 
Token: $BC (188) 


Coeration: Negative and zero arguments are tested for, and If found, the routine 


ROM 


plied with 7ILLEGAL QUANTITY ERROR. The series evaluation routine in 

still used; this calculates log x to the base 2. It ia a remarkably short 

it is 8, of 4 terms only. The argument goes through a series of conversionn: * 

ved Put into the range .5-.99999, the remalning exponent being saved on the 
k, Then 1/SQR(2) la added; the result is divided Into SQH(2); the result 

Peaeevudaaloe from 1, These transformations turn x lito: 

Peau) - L144 * 1), and log,x of this quantity la found. Then the 

The Is wubtracted from .5, renormuliacd and multlplled by log 2 to base e. 

th Poutine appears to be based on the standard oxpresslon for logarithms, 

@ seoring jlog(x} = (x-1)/ex41) + A/9%CK- 1) i (xtdy® ©... 


entry points: 


BASIC 1: SDaBF (65487) 
pple 4: $ner6 (65642) 
BIC 4: CH20 (539000) 


thi —e—E—e—————————————oo 
lieve the followilag dateils are correct. However, there may be errors. 
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LOMEM & HIMEM 


BASIC system command unavailable directly In CBM BASIC 


PURPOSE: Reserves a part only of the normal BASIC RAM for BASIC and its 
variables, freeing RAM for other purposes; these include storing machine 
code and storing graphics pages to be moved into screen RAM, 


Versions; Some micro BASICs have this instruction (Apple, (TT; Tandy has 
CLEAR n). In genera! no larger machines have this sort of command. So 
far ag I'm aware, no one has written explicit routines to perform this sort 
of memory allocation with BASIC; usually, ad hoc pokes do the job. There 
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MERGE 


System command unavallable directly In CBM BASIC 


5: BASIC keywords 


PURPOSE: merges two BASIC programs together Into a single program. 
Unlike APPEND the ranges of linenumbers within the two programs need not 
be mutually exclusive. In thia way, standard subroutines may be inserted 
into programs without the need for keying-in. 


Versions: The usual method invaives storing the subroutine{s) on disk or tape as 
sequential files ~ not as tokenlsed programs - then reading them dack by a 
routine similar to that used when adding lines from the keyboard. fm this 


are several possibilities which we can distinguish with the aid of diagrams: i fashion individual lines. one at a time, are merged into the initial program in 
This is the normal memory map of BASIC: i axel Cad seth! Burees Pong keeps the routine working until an invalid 
ece of is found. Normally, this is*READY.', written conveniently b 
$0400 Top of RAK {eg $8000 with 32k) i LIST at the end of the sequential file. As I say, this is the usual method: Tt 
H at two well-kn th: 
(i) We can lower the pointers to top of memory, creating a spare block of own methods, for tape and for CBM disk respectively. ° 
RAM at the high end, where strings would otherwise be formed. j [1] Tape Merge. 
$0400 ap H Use this routine to save the subroutine on tape es a sequential file: 
BASIC vars | Arrays Strings | *SPARE* H OPEN 1,1,1, "NAMB OF SUBROUTINE”: CMD 1; LIST (LOW ~ HIGH] 
This is easily done, in either direct or program modes. The resulting block : Where the square brackets denote optional linenumbers, when only a subset 
will be completely secure from BASIC, unless the locations are poked or i of a program is wanted for future merges. The program lists onto tape. 
corrupted. . “ ere een te sa ' PRINT#1: CLOSE 1 
POKE 52,0; PORE 53,48: CLR: REM SE or =$3000 BASIC>1 H ; 5 . 
PORES, 0: POKE49, 48: POKESO, 0: POKES1, 48: POKES2 , 0: POKES3, 48 t Close the file with these instructions when the cursor returns. This com- 
j pletes the first part of the operation; the named subroutine is stored. 


Both these versions have similar effects. Note that $30-48 in decimal, go 
$3000 has high byte 48 and tow byte 0 when using decimal pokes. 


(3) We can raise the end-of-program pointers, generating space after the 
BASIC program in memory. This happens automatically when one program 
loads another from disk or tape. Some BASIC igaders of long machine code 


routines like Extramon use this method. 
30400 Top 


psi pie ee [se 


PONK 43, PEEK(43)+4: CLR: REM RAISES VARIABLES BY 4*256 = 1024 BYTES 


This simple routine adds 4 to the high byte of the pointer to the end of 
program. The program will still stop running when it encounters three null 


bytes; the unusual positioning of its variables Is not relevant to its running. 


(iil) We can generate space before BASIC by adjusting the start of BASIC 
pointers. Some proprietary software has 4 Memfixt routine which does this. 
go4co Top 


This technique fm trickier than the others; It cannot for example be per- 

formed from within BASIC. A program modified in thls way will SAVE In 

a non-standard way and LOAD again from lta modifled starting address. 
POKE 40,L0; POMR 41,HE; POKE 256*HI+LO-1,0: NEW 


In direct moda only prepares memory for the keylng in of BASIC, where 
LO and HI (default values } ond 4) can be yser-selected), 


See et oe 


er tae 


-emertter crite + 


Fn mega en ~ 


Merging can be carried out now whenever you have a suitable program in 
memory; the result is a fully merged program, as if the lines had been 
separately typed at the keyboard.? Follow these instructions fairly closely 
(i.e. get the pokes and cursor movements right! ):- 


Starting with a program in memory and the tape in cassette #2, 


BASIC 1: POZE 3,1: OPEN 1,1,0, "NAME OF SUBROUTINE” 
BASIC 2; POKE 14,1: ditto 
BASIC 4; POKE 16,13: ditto 


This will read the tape untll the correct header has been found; now it 
will walt for the tape to be read. 


[CLEAR] and type (DOWN} [DOWN){DOWN] then: 

BASIC 1: PORE 6)1,1: POKE 525,31: POKE 527,13; PRINT [HOMK)"[RETUAN] 
BASIC 2: POXE 175,12: PORE 158,1: POEK 623,13: PRINT’ {HOME ]" [RETURN } 
BASIC 4; ditto 


The tape file ig now read and merged correctly, subject to the provisos in 
footnote 2. Eventually, ?SYNTAX ERROR or 70UT OF DATA ERROR appears 


depending on whether the program or the merged subroutine had the highest 


ilnenumber, This means the merge fs finiahed, 





ne 
fs “ tage routine ie t 
Hee of which thia iw the best. Bevoral disk versions exist; thia one is bosad on 

© Todd's (see IPUG newsietter, May '80). Brad Teapleton’s ‘Power’ EPACM usce an 


of Brad Templeton and Jim Butterfield. Various versions 


x 


é 
tty 


Bieter technique ta construct ftlea likes Apple EXZC files, onebting stored commands 

Pe ell the aching as though from the keyboard. The serging process can be routin- 

Wascig e.g, °PRT'’s Gibrarien' by D J David, kb-Microcomputing, April ‘AG, 

es shin the input buffer is 40 cheracters long, lines with abbreviated input (e.g. ? 

the T} may not merge correctly if they LIST with overtength lines; Lf thle happene 
relevant lines aust be seperated into phorter lines. 


(iv} There are other posalbilities. Chapter 2 hua demonstration programs 
in which varlablea (or varinbien plus thelr program) are confined to the 
seroen RAM, POKE 41,128: POKE 53,131: NEW: REM DISPLAYS 788 SYTES BASIC>L 


(v) Corresponding locations for BASIC 1, the oldest ROMs, are itated In 
the appendix of ROM and RAM addrossce. 


i 
i 
¥ 
b 
: 
a 
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(2}_ Olsk Merge. 
LDA #§08 

STA DEVICE NO 
JAR [EER TALE 


SET DEVICE to 8 (I.E. DISK) 
BST IMEE UP FOR TALE 


; 
LDA $63 7 3 OR'D WITH #$60 
STA SEC ADD ; SECONDARY ADDRESS 3 
JSR OUTPUT IT ; OUTPUT TO IEEE 
LDX #900 ; COUNTS BUFFER CHARACTERS 
JSR INPUT [SEE ; GET CHARACTER FROM IBEE 
CMP #SOA ; LINEPEED? 
BEQ ~7 ; EF SO, IGNORE IT 
CNP 4$0D ¢ CARRIAGE RETURN? 
BEQ +10 5 IF 90, FHOLE LINS INPUT 
STA $0200,2 ; STORE PROGRAM LINE CHR. 
IMX ; INCREMENT COUNTER 
CPX #351 ; 80 CHARACTERS? 
BEQ ERROR 3; IF 80, LINB I8 TOO LONG 
BNE -21 ; INPUT NEXT CHARACTER 
STA EKYBD BUFF ; STORE CARRIAGE RETURN 
JR PROC ; PROCESS LINE IN BUFFER 
LDA #313 ; (HOME) 
JSR $FFD2 ¢ OUTPUT IT TO SCREEN 
LDA #$02 s 1 CHAR IN KEYBOARD BUFFER 
STA ¥O CHRS ; 
JMP TOKENISE ; TOKENISE AND INCORPORATE LINE 


JuP ERROR LINE TOO LONG 


This rather schematic machine code iustrates the procedure by which disk 
merging can be made to take piace. Characters are read into the buffer. 
fust aa though keyboard entry was being used, and the line is processed 
and tokenised in the same way. After each line, (HOME] is forced so the 
routine is called again. The concept is similar to the tape merge. The test 
for lines of length 40+ protects the tables of file numbers, device numbers 
and secondary addresses if these are inuse; if, as ia likely, they aren't, 

a larger number than $1 may be used. 


Tha routine is retocatabte, but not transferable between BASICa. The 
versions below start at $027A (cassette #1 buffer) for compatibility with 
BASIC 4. 


Instructions. 
Where F is Logical file number, § is Secondery address, BD ia drive ouaber, 
Save a subroutine with: 
OPEN ?,6,8,"D:NAME OF BUBROUTINE, SEQ, WRITE" :CMO F: LIST [LOW ~ HIGH] 
Where the linenumbers are optional, When the fle is written, close it with 
PRINT#OF: CLOSE F 
Merge this subroutine with a program in memory by: 


OPEN 7,8,3,"D:NARK OF SUBROUTINE,BEQ,READ" then 
enter (CLEAR]BY6 634 [RETURN] 


BASIC 2 os 

+: O27A AY OW 85 D4 20 BA FO AD -}027A AD 08 85 D4 20 D2 FD AD 
«| 0282 63 85 D3 10 28 Ft AZ OO 12282 83 88 DI 20 43 F1 AZ OO 
«? O284 20 6C FI CA OA FO Fe CO ,:DZHA 20 CO Fl CO OA FO Fe CD 
.? 0392 00 FO OA 9D OO O2 RA EO .102592 OD FM) OA 9D OO O2 ES EO 
.} O20A OL FO 14 DO ED 8D 6F 04 ./029A D1 FO 14 DO £& AD AF 02 
-} Q@A4 20 DS CO AD Ld 3G D2 FF .:0842 20 D2 BA AG 13 2) D2 FF 
~$ OJAA AD OL 83 OE 40 26 C3 4C 10244 AD GL 65 9E 4C OP HA AC 
.1 0382 23 D1 .!:9282 73 C3 





tae mn re ar 


ween ee: 


“+ seep: 
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MID$ 


BASIC string functicn 


PURPOSE: Extracts a substring from a string expression. The substring 
consists of consecutive characters from the original string expression, and 
may contain zero characters, all the characters, or {usually) some inter- 
mediate number of characters from the string. BASIC 1 will not permit @ 
substring of length zero to be taken. 


5: BASIC keywords 


Syntax: MIDS{string expression, arithmetic expression(, optional arithmetic 
expression]). Neither parameter may take a value greater than 255. If 
the second parameter is omitted, the substring continues by default to the 
end of the string expression, like RIGHTS. The first parameter determines 
the starting point of the substring. See the diagram. 


Modes: Direct and program modes are both valid. 
Examples: 200 N$°MID$(STR$(N),2) : REM REMOVES LEADING SPACE FROM +VB NUMERAL 


620 ni$="EachPackUnitTubeReelSet PairRollutr “ 
643 for j#1 to len(ni$) step 4: 17 ja$=mid${ni$,j,4) then retura 
626 next: ok=O0: es$="in Price Unit": gosub 800: return 


1530 m0$2M1D$ ('"' JANFEBMARAPRMAY JUNJULAUGSEPOCTNOVDEC", 3*M~2,3) 
A$="ABRACADABRA": FOR J=1 TO 6: 79PC (J)MID$(A$,F,12-J}: NEXT 


These examples illustrate typical uses to which this substring function may 
be put. Firstly, line 200 uses the default option in which the second 
parameter ig omitted, This means that the string function, STRS(N), is 
converted into N$, starting at the second character of STRS${(N) and cont- 
Inuing to the end. So if N=23, STRS(N)=" 23" and N$="29". 


The program extract (tines 620-626, listed in lower case) is one of a set 
of input validation subroutines. lt checks that the string js$ which has 
been typed into the machine is one of the four-letter substrings held by 
ni$. If it is not, an error message routine is called. 


Line 1530 converts month number M (1-12) into @ 3-letter equivalent. 
Lastly, a loop prints symmetrical portions of the string A$ . 
Notes: [1] This diagram should make the operation of this function clear: 


xso"s [alu [e[ ele bp] s[ rt] ali} nice 
Position in string:(1 [2]3|4[ 5/6 |7{ &] {210 {12 [12 f13} 


PRINT MiIDS(X$,3,6) prints MPLE S which atarts at 3 and has length 6. 
PRINT MIDS(X$,5) prints LE STRING which starts et 5 and ends at 13. 


{2] The three functions MID$, LEFTS and RIGHTS resemble SIN, COS and 
TAN in that they ere closely related. LEFT$ contains the main proceasing 
for all three functions. In BASIC, doth LEFT$ and RIGHT$ can be put in 
tarma of MIDS, although the result ls not very readable: 

LEFTS(1$,N) is the same a MIDS(X$, 1,8) 

WIGHTS(X9,N) ta the came ne MIDS(XS,LEN(TE)-N+L). 


Abbreviated entry: ml (Includes $) Token: $CA (202) 


Operation: Sets the default for the second parameter to 25$. Then, If there is 
Not «a elght-hand bracket, checks and Inputs the comma and the second 
Parameter (overwriting 255). The atring parameters corresponding to the 
first two purameters (string and ntarting position) are pulled from the 
stack. If the string has length zero, 7ILLEGAL QUANTITY ERAOR appears, 
From this dsta, the true start position and tength of the substring sre 
calculated; snd LEFT$ in onternd to set the new atring up. BASIC 2 is 
logleaily identical to BASIC 4, but the old ROM diffore in several rospecta, 
mostly connected with valldation. 


ROM Qntry points: BASICL; $0607 (54790) BASICS: 9OGL1 (64802) BASICA: 0CNAD (51368) 
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MOD 


BASIC arithmetic functlon unavailable directly in CBM BASIC 
PURPOSE: Calculates the remainder when an Integer Is divided by another. 


Whenever a fixed numerical cycie occurs, a function equivalent to this is 
likely to be needed;exampies include 12-hour clocks, date processing where 
weekday is represented by 0-6, conversions between number bases, and 
check digits and check letters, The word 'mod' is an abbreviation of 
‘modulo’; thiy is a mathematical term, used in sentences like '4 = %9 modulo 9’. 


Examples; DEF FN MOD(N) = N - INT(N/D)*D : REM D=DIVISOR; RESOULT 18 MODULO D 


DelZ: H=FN MOD(16): REM CONVERTS 16 HOURS TO 4 O'CLOCK 
De& ; LaFN MOD(Y) : REM RETURNS 0 FOR LEAP YEAR Y. 

De? : WOePN MOD(2174): REM RETURNS 3; EG DAY IS WEDNESDAY 
DeZ56: PRINT FN MOG(50000): REM LOW BYTE OF $0000 15 50. 


100 ISBN$="095076500" 
110 TO: FOR Jnl TO 9 
120 T = T + VAL(MIDS{ISBN$,J,1))*(1i-J): REM CALCULATE CHECETOTAL 


430 NEXT J 

140 Dell: T = FN MOD ({T): REM FIND REMAINOER AFTER OLYN BY 11 
150 Te#11-T: REM SUBTRACT RESULT FROM 11 

160 PAINT T: REM NOW RESULT IS 1 - 16. 


The function definition is, I hope, fairly clear: it subtracts the nearest 
multiple of the divisor from the original number N which leaves a positive 
answer, [t returns 0 if the number {is an exact multiple of the divisor. 
Positive numbers are assumed throughout. Four examples follow, ail of 
which use this function. The fourth must be a familiar one to any program 
mer using an eight bit microprocessor. 


I've included a demonstration program which usea mod to calculate the 
checkletter of an International Standard Book Number. Checklettera and 
checkdigits are an interesting aspect of computerology which hardly existed 
before computers; see Chapter 17 for more on the subject. Briefly, an 
{SBN has 9 numerala followed by a checkdigit of 0-9 or X. The value of 
the digit is computed as follows: weights of iC,9,8,,...2 are assigned to 
the numerals in the ISBN. Each numeral is multiplied by its weight, and 
the resuits added. Finally, this number Is forced into the range 9-11 by 
taking the remainder when divided by 11. (Then {t is aubtracted from 
11, an extra, unnecessary step). Try the program with other ISBNs. You 
wil find that the final digit agrees with the printed value of T, or is X 
when T is 10. 


Note: [1] Generally, integera are held exactly by the machine, All the routines 


on this page produce exact values. If there is @ possibility of rounding 
errors, when using for instance expressions Ikke 3 * .33333333, the 
evaluation can be foolproofed by adding in a amali value: 


DEF FN MOO(M) = INT (.1 + N - INT(.1 + N/D)*D), 
where both .1s are necessary to ensure accuracy at avery stage. 
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NEW 


BASIC system command 


PURPOSE: Appears to erase any BASIC program currently In memory, together 
with all its variables, so that a completely new program may be entered 
from the keyboard. The effect Is similar to turning on the machine anew; 
LIST shows nothing. NEW however leaves machine code intact in RAM, 


NB: This instruction is not a formatting command for C&M floppy disks. 
See ‘HEADER’ in the disk commands reference section. 


Syntax: NEW has no parameters; it may be follawed by @ptional} spaces, but must 
be followed by a colon or an end of line zero byte. 


Modes: Direct and program mores are both valid. 


Examples: N&¥ 
$0000 PRINT “GOODBYE”: NEW: THIS WILL NEVER BE REACRED 


In either direct or program mode the effect of this command is similar; the 
program will no longer list, and the programmer ig returned to direct mode; 
"READY.' Is printed. : 


Notes: [1] Everything in the cassette buffers, program variables, screen RAM, 
stored machine cade, and most of BASIC, is untouched. Because the memory 
atili holds most of what it did before NEW, an inadvertently erased program 
can be recovered completely, except for the values of variables: see OLD. 


{2] Syntax or out of memory or other errors and anomalous results occur 
If the start of BASIC pointers don’t point to $0401, or if $0400 does not 
contain the normal 0 byte. Example; a machine code routine loaded from 
disk or tape sets the start and end pointers as for BASIC; the same point~ 
ers are shared. NEW does not hardcode the value $0401 into RAM, but 
relies on the sccuracy of the pointers to BASIC. The solution, apart from 
switching off or LOADing a BASIC program, is to set the pointers: 


PORE 40,1: POKXE 41,4: PORE 1024,0: NEW 


Operation: First of all the syntax of NEW is volidated; this simply uses a branch 
which ensures that NEW is a statement on its own. Now the following 
changes are carried out: Zero bytes are put at the link address at the 
atart of BASIC. in $0402 and $6402. The end of BASIC pointer is replaced 
by start of BASIC+2. CHRGET's address Is made equal to start of BAS{C-1. 
These changes are all that are needed to make the transiator regard the 
program as non-existent. Finally, things are tidied up with CLR: 
the variables’ painters are made consistent with a new program;i/O activity 
ia aborted; the DATA pointer and several flags are set to their default 
values. READY is printed, and the machine le prepared for « fresh pro- 


gram to be keyed in and run. 





Abbreviated entry: None 
Token: $AZ (162) 
ROM entry pcinta: 


BASIC 4: $f661 (80613) 
BASIC a: $CS8B (50823) 
BASIC 4: HASDS (48546) 
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NEXT 


BASIC command 


PURPOSE: Changes program flow of control to the statement immediately afier the 
matching FOR loop. If no loop variable is specified, the most recently en- 
countered FOR foop Is taken. In this way, loops may be automatically pro- 
cessed with relatively fess programming effort. 


Syntax: NEXT [real variable [,real variadle](,real variable} ...]. Square brackets 
denote optional variables, which must be separated by commas. 
‘NEXT WITHOUT FOR ERROR is generated whenever the foop variable does 
not match that currently in the stack, or if there is no active FOR loop on 
tha stack. See the notes for an explanation of this term. 


Modes: Direct and program modes are both valid. 


Examples: NEXT, Uke RETURN, operates on the 6502's stack, and can appear 


anywhere in a program. This type of es , 
structure, therefore, Is possible:- pe bi acl To 3: Cote 100 


30 NEXT J: BND 
But, even with its processing omitted, = : 
lt ts difficult to read. Straightforward 100: FOR Ket 20:22, 00TH ae 
nested loaps are therefore norma!. Inclusion of the loop variable has a smafl 
slowing effect on a loop, but on the other hand makes a loop more readabie 
since the corresponding FOR can he more easily found. Whenever the loop 
variable exists on the stack, but not at the mast recent level, one or more 
loops will be lost; this is the source of some fairly obvious bugs. For 
example, thls short program executes * 
correctly, but the J loop is aborted aa POR Ic] TO 10 
; ‘i FOR J=<100 TO 120 
repeatediy. Processing of this type 30 - 
peek IF <6 THEN NEXT I 
has one practical use, which is when 40 NEIT 3,1 
a loop is left prematurely, without . 
completion of the entire range of values. As far a8 BASIC is concerned, the 
loop is still usable and active. Another NEXT will cause the loop to be re- 
entered. Given a stacked FOR structure, with free-format NEXTs allowed, 
this is inevitable. Active FOR loops can cause trouble; thie program tine 


100 FOR Jnl TO 10000: GET X$: IF X9="" THEN NEXT: REM 50 SECS DELAY 


delays until a key is pressed, or for about 50 seconds. before continuing 
with the next Ilne. If this line ia within a loop, 4 keypress causes early exit 
ao that J replaces the other loop's variable as the most recent loop. (Try it- 
it's hard to describe). 101 FOR J#O0 TO 0: NEXT cures this bug. 


Notes: [1] How the stack works. Far those Interested, the following short BASIC 
am shows whet FOR 7 
program shows whet does: 10 POR PQe512 TO 480 ATEP -1 


The output Includes 18 bytes, Mike this: 20 PRINT PEEK(PQ), 
Linatheenber Pointer te BO by 30 NEXT 
(Baal eed hire 
(oid) 0 D)—-Value of Final variable in flesting-peint format (<4ts bert), 
Sign of stup (negate bese, 
ST -STEP mize. a flowting -powl faemat (2 - 1 pert le 
@ 49 20)-FoR token, Porter tb variable. of nop in RAM - 
Operation: FOR checks the ‘ayntax, and assigne its variable, setting It up lf need be. 
The stack Is nearched, and variable mismatches rejected. If it's a new yarlavle 
the stack is tested for at least 18 bytes’ space, All the parimeters are pushed 
on the stack whifa checking the syniax of TO and the arithmetic expresnions. 
STEP Ls assigned 1, then overwritten (fa STEP exists. Pinully, It drops through 
to RUN and continues with the next alutement. NEXT, If followed by variables, - 
acarchen for the fleat, tater reading iin lat, The FOR byte ia checked, then 
STEP in added to the loop variable In acc. #1, The resuit ls compared with the 
upper limit, and if lasn (or, with negative step, greater) CHRGET fenst. 
POR: BASIC 1:8C849 _ NEXT: AAKIC 1:90036- STEP: HABIC 1: 9C80C 
BASIC 2: §Ca6a BASIC 2:9CC20 BABIC 2:%CGAB 
BASIC 4; 98608 BASIC 4: §2D19 BASIC 4; 68731 
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NOT 


BASIC unary togicat operator 


PURPOSE: evaluates the complement of any arithmetic expression {within the valid 
range). Im the case of truth values, this has the effect of converting true 
to false and vice versa. This second case is by far the most commonly used. 


Syntax: NOT must be followed by an erithmetic or togical expression. An arithmetic 
expression must evaluate to within the range -32768 to 32767. Non integral 
values will be rounded down. 


Modes: Direct and program modes are both valid. 


Examples: § IP PEBK{X)=34 THEN Qe NOT Q: REM SWITCH QUOTES FLAG ON CHRS$(74) 
PRINT NOT 23456 
70 IF WOT OK THEN EM$="- pack type”: GOSUB 20000: RETURN 
1000 IF Del OR O AND NOT T$2"TAPR" THEN OPEN 15,8,15;PRINT#15, "10" 


The first exampie shows how NOT can be used to switch the values of a 
flag; in this example, Q true means that the quotes flag is set; when the 
next quote mark Is peeked, it is unset. This has application when writing 
special LIST routines in BASIC. The second, direct mode example, illustrates 
the numerical effect of NOT. The value is converted into a 2-byte integer 
and the bits ali reversed: in this example, 23456-$5BA0, so NOT 23456 is 
computed to be SA45F, which in signed integer terms = -23457. This adding 
of 1 is general, and is because the bytes are complemented, but not 2's 
complemented. The third example is a program line which tests the flag OK; 
if this has been set false, the error message routine prints a warning to- 
the operator, Finally, an example shows NOT in a logical expression. 


Notes: [1] A fuller exptanation of 2's complement numbers appears under AND. 


{2] NOT has a higher position in the hierarchy of logical operators than 
OR and AND. NOT therefore takes precedence if there would otherwise be 
ambiguity, NOT A AND 8 Is effectively identical to (NOT A) AND B. 


[3] The usual rules of logic apply to NOT, OR, and AND, and may help 
when attempting to decipher elaborate expressions. Three of these are: 
A=NOT (NOT A) 
NOT (A AND B) = NOT A OR NOT B 
NOT (A OR B) = NOT A AND NOT B. 
The second and third of these are sometimes called d'Alembert's rules. 
babel relationships can be demonstrated in many other ways, e.g. Venn 
en re 





NOT A OR NOT B 


NOT ( A AND B) 
Abbreviated entry: nO Token: $A8 (168) 


Operation: The exprexsion following NOT 1s evaluated, and if valid, converted to 
‘. epaainate number in floating-point accumulator #i. The dlagram applies 
ABICOL: 


Mi 
fot os 
Fixed-point here 


The contents of $62 are raversed and transferred to the Y register; the 
contents of $61 are reversed In ihe accumulator, A standard routine which 
converte A low and Y high into Moatlng-point form 1s called finally. 


ROM entry points: 
SABIC 1; ScDSe@ (83712) BASIC 2: SCOCF (53487) BABIC 4: $BECC (43844) 
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OLD 


BASIC command unavailable directly In CBM BASIC ' 


PURPOSE: Restores a BASIC program which has been inadvertently erased by 
NEW, tt does this by resetting zero-page pointers to the start of BASIC 
and the end. This has a further effect: a program LOADed from another 
program can have its pointers set correctly, so that (for example) a smail 
menu program can safely LOAO a much larger program. 


Versions; Several have been published: Practical Computing (Feb.61) has a 6502 
routine, which, however, does not set end-of-program pointers. Printout 


(Jan.'61) had several using Toolkit calis with BASIC; Compute! had an UN-NEW. 


My version below is relocatable and may be called from within a program. 
In direct mode the program will LIST and RUN as usual, 


Operation: To decide what OLD is to do, we can start by examining NEW; this 
(1] Puts zero bytes at the link address at the start of BASIC, $0401 & $0402. 
[2] Changes end-of-BASIC pointer to $0403, 
{3} Sets GETCHR address to $040c. 
{4] --- Enters CLR routine at this point --- 
Current string pointer is set to point to the very top of RAM. 
[5] 1/0 activity is aborted and files closed. 
{6} End of variables and end of arrays pointers are set to end of BASIC. 
{7} DATA pointer is restored/ some flags are reset/ the stack is reset. 


There is an inherent problem in distinguishing simple variables from arrays; 
this version therefore does not attempt this. The reversible steps are 1,2 
and 6. Therefore OLD needs to:- 

[1] Replace the link address in bytes $0401 and $0402, 


[2] Recover the end of program pointer. 
{6] Set the variable and array pointers to the end of BASIC. 


(1] fe carried out on the assumption that the next zero byte found marke 
the end of line; [2] assumes that three consecutive zero bytes mark the 
end of the program. [ have also assumed that BASIC starts at $0401, and 
included this value explicitly; this clears up some problems when machine 
code has been loaded, so the atarting address is assumed, by its pointers, 
to be somewhere else in RAM. 


This is a flowchart of the part of the routine which searches for the end 


of program: 
= 
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OLD .,. BASIC 4.0 
634 $0274 «= AG 1 LDA #$01 
636 $027C) = AD. S04 LbDY #904 
638 $0272 65 iF STA POINTRL LOAD UTILITY POINTER 
640 $0280 a4 30 ST: POINTRHE ; WITH $0401 
G42 $0282 =6A0 03 Loy #$03 
a44 $0264 «68 PiInDO INY 
a5 gozas— ss Bi 1F LDA (POINTRL) ,Y¥ 
aa7 $0237 DO FA BNE FINDO 
649 $0239 = Cal INY 
660 $0284 «98 TYA ;RESTORE LINK ADDRESS 
631 $0285 18 CLo > IN ($0401) 
482 9028065 AF ADC POINTRL ; BY FINDING THE NEXT 
684 $028k 4 =6A0 00 LDY #3090 + ZERO BYTE 
ase $0290 G1 28 STA (BASICL),Y 
658 30292 «AS 20 LDA POINTRA 
660 $0294 689 00 ADC #$00 
662 30296 «68 Iny¥ 
663 $0297) «991 28 STA (BASICL),¥ 
665 $0299 88 DEY ; ¥ NOW HOLDS #$00 


686 $O029A Az G3 TESTO LDX #$03 


663 $029C £6 iF TEST30 POI 
haa ba ;FIND 3 CONSECUTIVE ZEROS 





$70 $O29E BO 02 BNE NOINC 

672 «$0200 4-20 INC POINTRE + MARKING PROGRAM END 
674 $0242 BL 1F NOINC LDA (POINTRL),Y ; (SER FLOWCHART) 

676 © $02A4_—soDO FA BNE TESTO 

678 © $02A8—CCA DEX 

679 «$0247: SF BNE TEST3O 

gat $0249 OF LDA POINTRL 

683 $02AR 69 03 ADC #$02 ; ADD #2 TO POINTER TO 
@85 $02AD_—s«BS 2A: STA PROGENL : 3 ZEAGS AND STORE AESULT 
687 $02AF AS 20 LDA POINTRE {IN RND-OF-PROGRAM 
489 $0281 49 00 ADC #$00 

691 $0283 as 28 BTA PROGENH 

893 $02BS AC FO BS JuP CLEAR | CLR AND READY. 


Notes: (1] BASIC 2 Is Identical except that the last line must be replaced by: 
493 $0zp5 0 4: 79 CS UMP 8579 ; BASIC 2 CLA AND READY, 
{2} SYS 634 calls the routine as written; it ia telocatable, however. 


{3] The start address of $0401 need not be hard coded in: If your BASIC 
ig written to start eleewhere, use LDA $28/ LDY $29. 


{4] The original ROM (BASIC 1) equivalent ia this: 


OLD + QRICINAL ROM 


826 OZ3A AS 7A A4 7B 83 71 84 72 
834 90342 AO 03 CA Bi 71 DO FB CA 
42 $0340 98 18 65 71 AO OO G1 7A 
850 #0932. «AS 72 49 00 CH 71 7A 8B 
858 9095A #2 03 E4 7t DO O2 &% 72 
84 0362 BL 72 DO F4 CA 00 FR AS 
874 S036A 71 SF 02 85 7C AS 72 49 
882 80372 00 85 7D 4C 6A CS 
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ON 


BASIC conditional command 


PURPOSE: Branches to one of a Nist of linanumbers, depending on the value of 
the variable following ON. ON ... COTO and ON ... GOSUB are valid. 
This provides a readable method for programming multipie [F statements 
of the CASE type, particularly if the variable takes values 1,2,3, ... 


Syntax: ON arithmetic expression GOSUB linenumber,linenumber, ... 
or ON arithmetic expression GOTO linenumber,linenumber,... 
Note that ON ... GO TO js disallowed. 
If the expression, on evatuation, is outside the range 0255, the message 
WILLEGAL QUANTITY ERROR is generated. 
If neceagary the value iy rounded down. When the value=i, the firet line 
In the fist is the branch; when 2, the second, and so on. 


Modes: Direct and program modes are both valid. 


Examples: 1000 OM SGN(Z)+2 GOTO 2000, 3000,4000: REM FORTRAN CONVERSION 
86 ON 1 + 1O*RND(1) GOTO 100, 200, 300, 400, 500, 608, 700, 800, 900, 1000 


5: BASIC keywords 


6240 ON KX GOSUB 400,410, 420,430, 440, 450,460, 470, 480,490,500 ... 
6250 OM K-20 GOSUB590, 600, 620,620,630, 640 ,650,660,670,680 ... 


200 ON Q GOSUB 100, , 200,300 


The first example shows a three way branch, depending on the sign of the 
argument, When X ia negative, SGN(X)=-1 so SGN{X)}+2=1. So if X ie a 
negative quantity, the first of the three linenumbers obtaing, In the same 
way, if if has zero or positive sign, the second or third linenumber is 
chosen respectively. The language FORTRAN ('FORmula TRANslation'} has 
this teat; sample tine 1006 shows the method of conversion to BASIC. 


The second example is taken from a game, The random number generating 
function RND returns numbers in the range 0.600001 to .999999 (roughly! ) 
so the argument evaluates, after rounding, to 1,2,3, ..., 10. Bach of the 
routines has an épproximately equal chance of running. 


If all the options cannot be fitted on one line, they may overlap onto the 
next line, ap the third example shows. See note {1} for expianation. 


ON does not share the peculiarity that GOTO and GOSUB share, of allowing 
non-numeric characters in linenumbcra. However, it does treat null ilne 
numbers, as in Ine 206, as if they were line G. 


Notes: {{] If the varlable is 0, or 5,say. when only 4 linenumbera exist, there 
ig no error message; the program merely begins on the next line. This is 
the reason why lines 6240-6250 In the examples work correctly Lf X la 
between 1 and 30 or whatever. The reason for this behaviour is explalned 
below In the section on machine code operation. 


Abbreviated entry: None 
Token: $91 (145) 


Operation: Firstly, the argument following ON is evaluated and valldated. If, es 
it should be, the result Ie # single-byta numeral, this value is stored (in 
$42 with BASIC>1). Next, ?SYNTAX ERROR Is printed if the foitowing 
token Is neither GOTO nor GOSUB. (This Is the rcugon for OM .. GO TOs 
unaccaptabiiity), The token is stored on the rtack: on axit ft Is pulled 
beck Into the accumuiutor, 0 the routine knows which of the two commands 
to execute. Before this, however, the list of linenumbers t# processed. 
This le done in a loop. The first thing la to decrement the stored value of 
the parameter; if the resu/t ia zero exit occurs to either GOTO or GOSUB. 
{f the result was not zero, CHROET gata the next flxed-polnt nenumbar 
and stores it In ($11) with HASIC>1, Provided « comma follown, the loop 
continues, Soa variable value of zero la troated In effect as 756. 


ROM entry points :BASICL:9C843 (51287) BASICS: OCOGI (51283) BABI: SEEDS (47318) 
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OPEN 


BASIC input/output command 


PURPOSE: Enters a file's ‘logical file mumber' In a table, together with the device 
number end secondary address. When BASIC refers to a logical file, for 
example with PRINT#, the device and its secondary address are taken from 
the tables and used in processing. Also, where necessary, the device ts 
prepared for input or output, Tape files have a header either read or 
written; disk files' parameters are sent on the IEEE dus to the disk unit. 


Syntax: OPEN arith. expr. |,arith.expr. [,arith. expr. {, string expr.]j]. The 
first parameter is compulsory and must evaluate to 1-255 after rounding down. 
The second parameter is the device number, which must be 015, and is a 
hardware feature; see the table for CBM equipment’s device numbers. The 
third parameter is the secondary address, which again is a hardware feature, 
and may not be present on non-CSM equipment. The string parameter is a 
file name, plus, in the case of CBM disks, other parameters giving drive 
number and a0 on. ?SYNTAX ERROR, °DEVICE NOT PRESENT ERROR, and 
FILE OPEN ERROR return to direct mode, aborting files which are already open. 


Modes: Direct and program modes are both valid. 

Exampies: Note that, while a logical file number is compulsory, the remaining para- 
meters are optional. The device number, secondary address, and strirg are 
assigned 1 (i.e. cassette #1), G, and null string respectively. in ali versions 
of BASIC. All the parameters are evatuatable expressions. 


Tape; OPEN 10:REM =OPEN 10,2,0,"" WHICH OPENS FILE #10 TO READ #1'S HEADER 
OPEN 1,1,0, "TAX": OPBN 2,2,1,°TAX UPDATE": REM SYSTEM WITH 2 CASSETTES 


Disk: OPEN 15,8,15: REM OPENS ERROR CHANNEL TO CBM DISK AS LOGICAL FILE #15, 
OPEN 1,8,4,"#": REM QGPENS A CHANNEL TO A DISK BUFFER FOR 8-R, B-¥. BIC 
OPEN 7,8,4,"0: ORDINARY FILE,SEQ,READ": HEM OPEN CBM FILE FOR READING 
FILE$="1: FILE A“; OPEN 3,9,10,F1$+"SEQ,"": REM OPEN PILE FOR WRITING 


Other: 10 INPUT "OUTPUT TO DEVICE #"; D: OPEN D,D 


20 PHINT#D, ...:REM PRINT OUT TO SCREEN OR PRINTER BTC, DEPENDING OW 
D + 2.6, 3eSCRERN, CONTROL CHARACTERS MUST WORK WITH BOTH DEVICES 
30 CLOSE D 


Tape files alwaya start by reading or writing a header. So two files to the 
same cassette are impossible, Our examptes show a header being read into ita 
buffer (where Incidentally it may be examined by PEEK) and OPEN statements 
for a 2-tape system, where data input from #t may be processed and output to 
#2, The disk exampies (BASIC 4 has DOPEN, which is slightly easicr} open 
files numbered 15.1,2, and 3, all to devica 8, the normal disk device number. 
It ta sometines wathwhile to open files to the keyboard and/or screen. 


Notes: {1] CBM Equipment and Its Secondary Addressing. 


Unasnlgned| 6,7 
Blak Driven 
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Ag the table shows. many primary and most secondary addresses are unused 
so that secondary addresses may be picked at random in most cases, WIth 
disks, secondary addresses 3-14 may be used freely. The parameter can’t 
simply be ignored, since the default value of 0 prevents a string being sent 
on the LEEE and anyway is compulsory before the string. This is why the 
exampies of OPEN involving disks have rather miscellaneous third paramet- 
ers. The keyboard, sereen, and non-CBM printers can be opened as files 
simply with OPEN 1,0: OPEN 3,3: OPEN 4,4 or with whichever logical file 
numbers you like, Cassette files are, on the other hand, entirely dependent 
for their correct operation on the secondary address. The default value of 
zero is (sensibly) equivalent to reading a file; 1 causes a norma! write; and 
2 causes an Identical write, plus, at the end, a ‘header’ holding a value 
which is interpreted as ‘end of tape’. 


CBM printers ere designed with many secondary address features, many of 
which, unfortunately, don't work correctly or are absurdly complicated to 
use. Output to these printers is consequently often formatted in ways not 
compatible with output to the screen or to other printers. The 4022 has the 
following secondary addresses: O-print ‘as received’; l=print in format; 2= 
store format; 3=lines/page; 4=error messages on; 5=define own character; 
G=set Iinefeed space; 7=upper case; 8='lower case’; 9-error messages off; 
end 10=reset. Some models of printer have 4 and 6 transposed. 


{2] RAM Tables. Three tables of ten entries each hold logical file numbers, 
device numbers, and secondary addresses as they are used by the IREE bus 
or cassettes. They start, and may be peeked, at 593, 604, and 613 decimal 
respectively. (579,588,598 in BASIC 1). The number of entries in the table 
ig stored in another location (i74 or SAE; 610 or $0262 in BASIC 1), The 


overall effect is as shown in the diagram: Kon: 4 LOGICAL FILE 
Any new OPEN has its logical file number $94 5 NUMBERS 
checked against those already present, and $95 15 

FILE EXISTS ERROR reveals duplication. 590 8 

BASIC 1 is inedequately protected against ...... 

OPENing more than 10 files. Later BASICS 403 4 DEVICE NUMBERS 
print 7TOO MANY FILES ERROR. POKEs 604 4 

inte these tables can cause problema, as 60s 8 

spurious 'files' may apparently exist. 606 8 


te hene 


OPEN 4.4: OPEN §,4,1: OPEN 15,8, 15: 
OPEN §.8,8,°0:DATA,S,R" gives the tabled 012 29% SECONDARY ADORESSES 
values, 615 111 

616 104 


[3} BASIC 4has DOPEN; It also has a modification of earlier BASICs: PRINT# 
followed by a logical file number with bit 7 low (i.e, 1-127) does not send a 
llnefeed character with a carriage return. Eariler versions did. This wae a 
result of the fact that PRINT referred to the sereen at first; later, the tape 
processing system was arranged to omit Iinefecds, but the IEEE bus stlli trans- 
mitted them to disk. On this subject, see PRINT#. 


(4] Other locations. OPEN sets these locations: SD2slogical file; SD4adevice; 
$D3=aucondary sddrose; $Di-length of string and, if this ls non-zero, 
(SDA) polnts to the start of the string. 


Abbraviated antry: oP Token: $9F (159) 


Operation: Chapter 13 has a schematic disanaembly of thls conuaand. The vorsion 
In BASIC>1; BASIC 1 le weitten iens concinely, dut is otherwise logically 
almilar. Flratly, parameters are fetched from WASIC by a singta ROM sub- 
routine. This part can be skipped In maching-cade programming, by setting 
the variables directly. ST is Ket to zero and the file lable entries nade, (ft — 
there's room, Tho [EEE bun, aa uaual, Is procespedd differeatly from the acraen, 
keyboard, and cassettes. The atring id sant ta the [EEE device only If the 
aeconilary nddrosn ia non-zero, and the string Is not the nuit airing. 


ROM entry points: OPEN Is a ‘kernel’ command. Ite addreas la $¥PCO. 
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OR 


BASIC binary logical operator 


PURPOSE: Caiculates the logical Inclusive OR of two expressions which evaluate 
into the range -32768 to 32767. The result is a 2-byte integer. With logical 
expressions, the result is true if eithar of the original conditlons were 
true, or if both conditions together were true. 


Syntax: Arithmetic or logical expression OR arithmetic or logical expression. 
Both expressions must be integers within the signed integer range, or 
floating point numbers within thia range when rounded down. All logical 
expressions are valid, since they take values of -1 or 0 only. 


Modes: Direct and program modes are both valid. 


Examples: 100 EF At<t OR A%>10 THEN 7 "OUT OF RANGE" 
PRINT ~1 OR 12345 
PRINT 380 OR 75 
6270 OK"OK AND D ¢ 32+ (M=40RM*GORM=S9ORM 911) + (M=2) # (3+ CINT(Y/4)* 427) 
150 IF NL=60 OR TY THEN NL#2; TFP#0: GOSLB S000; REM NEW PACE & TITLE 


The first and fourth examples show typlca! applications, where OR checks 
the range of a single variable: the first example ia, 1 hope, self-explanatory. 
The fourth is part of a date validation routine, which checks that the day 
of the month is acceptable, (NB: a leap-year test is included). It takes 
advantage of the fact that 'true' evaluates as ~-1 to calculate the acceptable 
upper limit of the day number. The second and third examples, on the 
other hand, do not compute logical functions, but operate directly on the 
numeral values: -1 ORed with any valid number leaves that number unalt- 
ered, because -1 is stored as $FFFF, and this pattern of bits, all ls.nas 
no effect when ORed with any other bit pattern. PRINT 380 OR 75 gives a 
bit pattern of 00000001 01111111 = 393; ep. AND. The final example shows 
OR used with different variables: a new page and two-line title ia to be 
printed If either 60 lines exist on the page so far, or some other condition 
hes set TF to true, for example change of client name. 


Notes: [1] The use of -7 for ‘folse' is not universal: Apple for example uses +}. 
Routines which run on o particular mochine may need changes of sign if 
they are to be used with another, 


[2] 'OR' is lowest in the operator hierarchy, and ia performed after NOT 
and AND. Because of this, PRINT 1 AND 2 OR 3 prints resuit 3, which 
is also obtained from PRINT (t AND 2) OR 3. PRINT it AND (2 OR 3) is 1. 


{3} The truth table for OR is:- 
OR{T F OR{1 0 Where i='true’ or ‘bit set on' 
1 s'false’ or ‘bit set off". 
PIT F oj1 0 
The following relationships are fairly easy to demonstrate: 
A OR B Is equivalent to NOT{ NOT A AND NOT B} 
A EOR B ts equivalent to A OR B AND NOT (A AND B} 
And these Venn diagrams show the difference betwoen Jnclu 


exclusive OR: 
AZOR BB] A B 


AQRB IA 
Abbreviated entry: None Token; $B0 (176) 


Operation; Identical to AND (q.¥.) except for the use of a location holding #SFF 
which the ROM routine uses to revarse bytes. 


ROM antry points: 


BASIC 1: SCXD (52950) 
BABIC 2: $CECA (52936) 
BASIC 4; $CO8H (49288) 


$: BASIC keywords 
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PEEK 


BASIC arithmetic function 


PURPOSE: Computes the decimal value of the contents of any memory location, 
PEEK, in conjunction with SYS and POKE and, to a lesser extent, USR, 
allows free access to RAM and ROM. Uses include: examination of ROM. 
of BASIC, and of variables and pointers; examining hardware locations; 
examining machine-code; and performing memory moves. 


Syntax: PEEK(arithmetic expression}. The range is 0-655235. 
Modes: Direct and program modes are both valid. 


Examples: PRINT “{CLR]" CBR$(34);: FOR J=1024 TO 1200: ?CHR$(PEEK(J});: NEIT 
100 FOR J#1024 TO 1100; POKE 31744+J, PEEK(J): NEXT 
7G7S FOR L9=4BT0S4: O$(7)=0$(7)+CHRS (PRE (LT+LS))}: NEXT; REM SIZE 
2000 LF PEEK(2$2)=1 THEN PRINT “SHIFT KEY IS PRESSED" 


The two first examples, apart from the minor difference of mode, carry 
out similar functions. Each displays about 1000 bytes of a BASIC program 
directly on the screen, so that literals, tokens, linenumbers and so on are 
all made visible. The main ditference is that the first example prints the 
characters, and so may fall foul of Commodore's special characters. The 
quote mark at the start prevents this, at least until 4 second byte holding 
94 is found. The second exampie doesn't have this problem, and is a 
routine to memory-move the program into the screen area. Try them both. 


The third example is a line from a program, in which information stored as 
@ file in RAM is now PEEKed out again. 0$(7) is the 7th string to be 
output, has length 6, and is the size description of the item. 


The final example shows how knowledge of the system may be used in a 
program. When the keyboard scanning routine finda the shift key depressed 
it aeta a flag which affects the character printed. The actual figure applies 
to BASIC 2 and BASIC 4. (BASIC 1 uses 516). 


Notes: [1] BASIC 1. This ROM contains a test ensuring that addresses from C000 
to EOFF have a PEEK of 0. This protection has been dropped in all later 
ROMs. BASIC 1 also has a bug, caused by the fect that a pointer it uses 
is shared by the function processing routine. Line 100 in the examples, and 
routines generally with several different PEEKe in a statement, don't work 
in BASIC 1. For both of theese reasons PEEK may weil be replaced by USR 
with this ROM. 

DATA 185, 8,72,165,9,72,32, 208, 214, 160,0,177,8, 168, 104,133,9, 104, 
133,8, 74,135,210; REM BUG-FREE FERE FOR BASIC 1 WiTH USER. 


The 23 bytes above give a peek routine for BASIC 1 JSR DADO 
which ig bug-free, so that PRINT USR(50000) prints Lpx #00 
208, and POKE C, USR(D) transfers ihe contents of LDA (08,%) 


Dto C. The 12 byte version to the right removes TAY 
the CO00C-EGFF protectlon, but doesn't correct the bug = TXA 
concerned with function processing. JuP 1278 


(2) A double-byte peek or DEEK is often convenient and can be written as 
a function definition: DEF FN DREX(X) « PEEK(X) + 256*PESK(X+1) 


Abbravieted entry: p& Token: $02 (194) 


Operation: BAS(C>1 suven the contents of ($11) -on the stack. (The omission of 
thie step Crom BASIC 1 causes Ita bug). The routine to validates and con- 
vert a floating point number from 0-65595 In called; this also stores the 2 
byte adilresa In ($11), or ($09) with HASIC 1. 1¢ is & strolghtforward 
matter to lond the accumulstor fram thea uddress pointed to, restore the 
original contents of ($11), and jump ta the ROM routine which londna the 
accumuletor with #0 and converts Y to flouting-point. ASIC 2 hns 8 NOPs 
left from BASIC I's protection routine, which are dropped with BASIC 4, 


ROM entry polnta:BASIC1:$0ER6 (66014) BASiCZ:$06ES (66016) BAaIC4: 90943151699) 
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POKE 


9ASIC command 


PURPOSE; Each POKE replaces one RAM location with the byte value specified by 
the second parameter, With PEEK and SYS and to a lesser extent USR, 
POKE enables RAM to be freely accessed from BASIC. It is useful when 
entering machine code from BASIC, modifying pointers, programs, variables 
and files in RAM, and putting characters directly onto the screen. 


Syntax :POKE arithmetic expression, arithmetic expression. The two parameters 
refer to the location and the byte. Their values must be within the ranges 
0-65535 and 0-255. A POKE into ROM or into an area not occupied by RAM 
or ROM does not print an error message, and has no effect. 


Exampies: 1. FOR J=0 TO 258: POKE 8*256*16+J,J: NEXT 
44. 10 DATA 162,0,198,157,0,128, 232, 208, 249,98 
20 YOR J=826 TO 835: READ X; POKE J,X: NEXT 
dia. 10 REM ASCRREROTCEBRECHH RATA KEAORE TE 
20 INPUT Y: POR X=0 TO 9: PORE 1032+X, X+¥: WEXT 
iv. FOR J=2000 10 9£9: POKE J,170: 1F PEEK(J}=170 THEN NEXT 


The four examples don't cover specific aspects of CBM BASIC operation, 

of which there sre innumerable possible varlations, See for example the 
notes in this section on HTAB/VTAB for zero page pokes, on DEL for pokes 
which contro] the keyboard buffer, and VARPTR for hunting variables in 
order to modify them by POKE. 


Example t is a simple loop which pokes ta the screen. Since this starts at 
$9000, the values 0255 are taken and poked into the screen starting at its 
top left corner. (The calculation computes $8000 in decimal each time round 
which is slow but easy). Example ii illustrates how machine code routines 
may be poked into memory. The loop reads data.one ltem at @ time and 
pokes it into consecutive locations, SYS 926, executed after this short 
program has been run, produces in machine code the same effect that the 
BASIC routine achieved. The speed increase is considerabie. 

Example iii is a self-modifying BASIC program in which 10 conaecutive bytes 
are POKEd into a REM statement. It provides an easy way to discover 
which tokens correspond to which values in BASIC, 

The last example ie a RAM test in BASIC. It performs a similar checking 
function that BASIC>1! executes when switched on. Locations 2000 and over 
are poked with {70 (bit pattern $10101010) and read back; this ia repeated 
until the PEEKed value [3 no longer t70, marking either the end of RAM or 
a defect in a location. This procese is far slower than machine-code. 


Notes: [1] Thia command is not part of standard BASIC, and is mlasing on most 
larger machines to avoid the risk of changing other people's work. It Is 
sometimes given other names, for example STUFF, on microcomputers. 


(2) A double-byte POKE or DOKE cannot be implemented ae a function 
definition, but requires a subroutine. DOKE Z1 (0-65535), 22 (0-65535) Ie 


POKE Zt, Z22-INT(Z2/256)*256: POKK Zl+1, 22/258: REM LOW THEN HAIGH 


(3) This command is one of the faw with a very simple machine-code 
equivatent, which examples 1 and {I illustrate. POKE 8*256*16,0 and 
LDA #$00/ STA $8000 exch put a zero byte in the top [eft of the screen, 


Abbreviated entry: pO Token: $97 (151) 


Operation: The parameters are evaluated by a subroutine shared with WAIT which 
evaluates and checks the first parameter, and convorts this into a fixed 
point number which is stored In ($1) with BASIC>1. The comma and noxts 
Parameter are checked, and If the parameter is within the range 0-255 Itla 
put Into the K register and stored in the address In ($12) without a 
Peadback check. All the ROMs process this command similarly. 


ROM entry points: BASIC: §D4PO (55033) BABICI: $0707 (08047) BAKICA, SCDDA (51640) 
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POP 


BASIC command unavailable directly in COM BASIC 


PURPOSE: POF discards the Jast RETURN address from the BASIC stack, This In 
effect makes the previous GOSUB no longer effective, so that, if a RETURN 
is encountered, the address returned to will be the COSUB before tast's. 
This is useful in escaping from subroutines. For example, suppose a user 
is to be allowed to exit from a subroutine directly back to a menu, perhaps 
if the wrong routine is entered by mistake. Jt can often happen that a 
direct GOTO leaves the subroutine stilt active. Or imagine a game, written 
so that a long sequence of games can be played, and containing a routine 
totest for end of game: the test may check whether one player has collided 
with the board edge. Ifthe test routine jumps straight to the routine which 
prints the score, after 24 or so games the program will stop with an 7OUT 
OF MEMORY ERROR. 


Note that from the point of view of structured programming, this command 
ought to be unnecessary; such program demands the use of subroutines 
with one entry point, one exit, and no irregular exits with GOTO or POP. 


Versions: The only previously published version I've seen is by Tom Mead, in 
the Liverpool Software Gazette (Oct.'80), My routine which follows is based 
on the RETURN command in BASIC and mimics this in alf respects, except 
for the ectual change in program control, So the address is erased but the 
program continues with its next statement, without a change in the flow of 
control. If there's no address on the stack to be popped, ?RETURN WITHOUT 


GOSUB is printed. 
DEMONSTRATION {ALL ROMS) 


ae 
iET X@0 IF Xe="" GoTo i 

‘F ASC(X#)=13 THEN PRINT PRINT A®t RETURN 

‘F X@e"xX" THEN SYS 4341 SYS 424; GOTOZ0 

RINT XO¢e AS2AS+XH. COTO & 

FoR f = 1 TO 4: PRINT I#¢ GOSUB 03 NEXT: RETURN 

PRINTs PRINT “MENU"e GOSUB 10, PRINT "END": END 

FORI « 634 TO 657: READ Xs FOXKE [+ X+NEXT+ COTO 20 

DATA 1697) 255+ 133) 1522 32: 172) 194+ 154 20161416 240. 3+ 162122 
DATA 76:09) 19S + 232+ 232+ 2Z3Ze 23Zr 2922154076 


>) REM 
x) REM AON ESOEENESDREDENAEEEERRSESEROEEEFRERELAEESOREEHENEOR THESE TENET EDD 


lO REM # “RUN 50’ DEMONSTRATES POP AS AN ESCAPE KEYe TAKING USER BACK * 
20 REM *# TO MENU WHEN HE’S SELECTED A WRONG OPTION: X USED AS ESCAPE. « 
30 REM * NOTE THAT POP WITHOUT GOSUB GIVES 7RETURN WITHOUT GOSUB ERROR, # 


$6 REM SREESHESEEAPRERREEEHHEEEROEEERDEEEEEGHOEEHHE OEE SEEDERES ED HERD SEEREE 


30 REM 


73 REM 
20 REM SREPEEREEREHHERE DED EERETEOHHHES HEED ESEEREREHHEFREREESEOREN HERE OH 


LO REM # BASIC 3 VERSION [68 VERY SIMILAR: 

20 REM # 32 DATA 169,253, 193+71592+170) 194) 454+ 2015 141+ 2400 3- 142+ 22 

30 REM * 54 DATA 76:87+ 19S) 232» 2I2Ze 2321 232s 2AZe 1542 FH 
¢ 
* 


ne 


40 REM 48 169 BASIC 4 VERSION: 
30 REM 52 DATA 169) 255+ 1599-72052) 34217991540 2019 141 2401 Se 162; 22 


40 REM ® 54 DATA 7b 2070179) 232+ 232) 232+ 232+ 23592+154,>94 
70 REM CHESPOS EEN RETEHEEEEEAHE SHOR RNOEHEEERA CFL ONESEOSESOHAHEOOETERNE Bane 
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POS 


BASIC arlthmetic function 


PURPOSE: Computes the position of the curser on its current screen fine. 
Yhe range is 0 255. This is not the position on the sercen line, but a 
measure of the distance the cursor has moved along its present line: some 
PRINT statements can return a value up to 255; more usually, when 
keying - in program lines for example, the maximum is 89, 


Syntax: POS(expression). Like FRE, POS uses a dummy variable, the sole point 
of which is to make POS behave like a function, POS{0), POS{X), POS(""} 
are all yalid options which yield identical results. 


5: BASIC keywords 


Medes: Direct and program modes are both valid. 


Examples: 61540 [F POS(0)+PEEK(196)>74 THEN PRINT CAR$(34); “(HOME } (DOWN) [DOWN] 
La" L "¢i:8e" J ":E=" BE ":GOTO" G 
PRINT TAB(10)POS(0}: PRINT SPC(10)PO3(0) 
100 PRINT LEFTS(" ",12-POS(0)) , I$ 


POS Is arguably the least useful of all the BASIC keywords. Nevertheless 
it performs some useful services: the first example is taken from a routine 
which automatically writes the cantents of RAM as DATA statements. If a 
system has no facility for dumping memory, as a RAM image, or if RAM 
has a relocatable routine, handling it as DATA may be convenient. The 
program line checks whether the data 30 far printed to the sercen is in 
danger of reaching the end of the line. (In BASIC>1, location 196 holds 
40, with a 40-column screen only, if printing is on the line one dawn from 
the top of the screen). 


The second example is a direct mode line. The third figure printed 
depends on LEN{X$). If LEN(X$)=200, PRINT POS(0} returns 200. 


The third example itustrates the close connection between POS and TABC. 
If POS(0) is confined to the range 0-12, line 100 is equivalent to TAB(12). 
Suppose that the cursor 1s at position 4: then 8 spaces will be printed 
before X$, so the effect is the came as TAB(12). 


Notes: [1] POS uses the same parameter as TAB(. Consequentiy POS cannot be 
used with printer commands unless the identical line ia printed on the 
Bfereen. Its usefulness ia in practice imited to the screen. 


Abbreviated entry: None 
Token: $B9 (185) 


Operation: Loads the ¥ register from the zero-page location storing the position 
of the cursor on its ‘line’. This location Ils $C4@ (198 decimal), or In the 
case of BASIC 1, locatlon 8. The accumulator Js loaded with #0 and a 
ROM routine entered which converts A und Y, as high and tow bytes, into 
floating point form in accumulator #1. 


All ROMs uae Identical logic to process this function. {The absolute 
addresses differ). 


ROM entry points: 


BASIC 1: $0285 (53803) 
BABIC 2: $D27TA (63882) 
BASIC 4: SAC (50377) 
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PRINT 


BASIC output command 


PURPOSE: Evaluates and prints string expressions and numeric expressions to an 
output device, usually the screen. The appearance of the output Ia to some 
extent controllable by the punctuation of the statement, and also depends 
on the speciel graphics and screen editing characters of CBM BASIC. 


Syntax: PRINT followed by arithmetic and/or string expression(s), separated from 
each other by one or more of: SPC(erith, exp.), TAS(arith. exp.), space, 
comma, semicoion, or no separator where this causes no ambiguity. 


Each string and arithmetic expression must be valid and also evaluate within 
acceptable limits when the PRINT statement is run, The parameter for TAB 
and SPC must evaluate to within the range 0-255, after rounding down. 


The statement terminates when a colon or end-of-line zero byte fs found as 
part of the punctuation (i.e. not within quotes), See also the flowchart. 


Modes: Direct and program modes are both valid. 
Examples: FOR J=0 TO 255: PRINT CRAS$(J);; NEXT: RE PRINT EVERY CHARACTER 


FOR J=Q TO 100: PRINT J, NEXT: REM SHOWS USE OF ‘,° 
PRINT X+¥; 124; PeQ*{1+R4/100): REM ARITHMETIC EXPRESSIONS 
PRINT "HELLO"; ASS$C$; LEFT$("ABCD",2):REM STAING EXPRESSIONS 
100 PRINT T1;TI$;ST,DS; DS$: REM SPECIAL VARIABLES 


These five print statements illustrate most of the major features of PRINT 
except TAB( and SPC(, which are explained elsewhere. The first is a loop 
which uses PRINT to output ali 256 individual characters. The effect of the 
loop varies with the ROM; 80-column CBMs have a tremendous range of screen 
editing characters, so characters shift about and disappear, eventually, as 
the scrolilng window becomes set, confining themselves to a small rectangle on 
the screen. Other CBMs are more sedate, merely clearing the screen and 
homing the cursor. The semicolon ensurca that alphanumerics print next to 
each other; in the next example, the comma tabulates numbers into every 
40th column, The third and fourth examptes show typical arithmetic and string 
expressions respectively. Each expression is evaluated and printed from left 
to right, taking account of punctuation. Note that the arithmetic expresaions 
are printed in the standard Microsoft format explained elsewhere. Semicolons 
have been omitted from the string output example; in fact, ASBSCS prints the 
three strings one after the other exactly as A$;B$;C$ would. This is because 
the '$' aymbol is recognised aa a terminator. Similarly, @ gemleolon is not 
necessary after an Integer's '%' or an array’s ‘)'. Numeric variables require 
more careful punctuation, since their namea allow o mixture of alphabetic 
charactera and numerals. PRINT X+Y 124 is interpreted aa PRINT X+¥1, as 
an example. This sometimes causes wrong output, but errors in PRINT 
statements are eagy to correct, Finally, note that PRINT has routines within 
it to check for specinl vatues, including pi, the status indlcetor ST, TI and 
TIS, and (BASIC 4 only) the disk status variables DS and DS&. 


PRINT (7) (7) :REM PRINTS 7 F 

PRINT 1,2..3 :REM PRINTS 1.2 0 13 ['.' sppears ‘Oo "J 
PRINT READY. :REM PAINTS O O [i,e. values of RE then 0] 
PRINT ;, LK4°R6A;4 REM PAINTS 0 4 (i.e, ',’,LR*Rd, then 4) 


PRENT 1/3(5¢+--3).51 :REM PRINTS § .93339333) 10.51 


Graphics. PET graphice characters are usually printed to the acreen from a 
ateing in quoter. (Tney can also be poked directly inta acrnen HAM). [RVS] 
ig necessary to complete the character wat, and doubles the number of available 
graphics. This extract from a program Hating (in upper case mode) shows 
the type of thing: 

1930 PRINT® —B4 L.—* K—————" 

1055 PRINT’ IM AIT COSTA “F8C3)" e—_——5* 

166@ PRINT" Im IOMEe “J8C6>"OIM FIXED? “Ja<7 >" (* 
1863 PRINT" I “RPORTa “J#<92"°D1I9 FIMEQ? “JS¢99 "DI" 


« 
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Notes: [1] The screen appearance is controlled by three factors: ({) The character 
generator ROM, (ii) Programmable hardware features, and (ili) The ecreen 
hardware. Taking these in order:- 

(i) The oldest PETs use a character generator with upper and lower case 
trensposed, a transitional feature from the days when upper-casc was normal, 
eo it seemed natural to produce tower-case with a shift key. All subsequent 
ROMs use the normal typewriter convention. The ROMs are incompatible. 
(ii) POKE 59468,12 and POKE 59468,14* switch between upper case and 
gtaphica (no lower case obtainable) and lower case with upper case (losing 
all the QWERTY graphics, such aa the card sult symbols}. Try 

O POKER $9468,12; POKE 39468,14: GOTO 0 
to see the effect of this on a screenfu! of charactera. 

POKE 59458,62 is one of several equivalent fast-screen pokes, which 
cause « large and useful speed increase when printing to the screen. 
CAUTION: GASIC & CBMs have improved screen printing speed; this POKE 
wil! not work, and can cause damage to the machine, 

With early PETs and CBMs, this is perfectly safe and necessary if you wish 
to avoid slow screen printouts. The rule is; if the picture on the screen 
eollapses, don’t risk it again, 

. Wide-screen CBMs have a CRT (cathode ray tube) controller chip. This 
is programmable; see Chapter 9 for details. 
(Hi) The oldest PETs used a blue-white phosphor, Ali recent machines use 
green, Since about mid-1981, 12" screens only have been fitted, on 40 column 
and 80 column models. There is some incompatibility, as might be expected. 
between 40 column and 80 column PRINT statements. A program designed for 
40 columna typically looks similar on an 80 column machine, but uses only the 
leftmost 40 columns - unless PRINT statements have been terminated with semi- 
colons, in which case the top half of the 60 column screen will be filled with 
double lines, Also of course BASIC 4 curser control characters will not work 
on other ROMs, so scrolling windows, line erase characters and so forth 
cannot be downward compatible. 


{2] The reverse key is necessary to obtain some characters:~ 


PRINT “[R¥S] (DOWN] [DOWN] " ;REM REVERSE SPACE Id A SQUARE 
PRINT “(RYS) »{RY¥SO] " }REM PRINTS FF 


Thia meane that it {s not alwaya easy to convert a picture on the screen into a 
set of PRINT atatements. Homing the cursor, then typing linenumbers followed 
by ?° and RETURN doesn't accept reversed characters; a tedious procedure 
of inserting [RVS} and [RVSO] will need to be used. 


Abbreviated entry: ? 
Token: $99 (153) 


Operation: The flawchart, which applies to all the ROMs, outlines the way PRINT 
works, It is not @ particularly long routine ~ a page or two of listing paper - 
but calle half a dozen or so other ROM subroutines, 


ROM entry points: 


PRINT: [8Y8 of this BASIC 1: SCOOP (51618) 
addresa-6 hea the sane BASIC 2: $C9AB (51627) 

effect as PRINT] BABIC 4: $BAA8 (47734) 
SUBROUTINE TO PRINT ONE BTRING: 

Accvaulator holde low byte, BASIC 1: $CAQ? (51781) 


Y-regiater high byte, of start BASIC 2: $#CA1C (51740) 
Of atring; tarainated by null, BASIC 4: $DBID (47901) bas some changes 


OUTPUT ROUTINE FON SINGLE CHARACTER: 


Controls which character, if any, BASIC 1: QCA44 (31760) 
Will be printed: has 45 entry BASIC 4; $CAI9 (617869) 
polnte. BASIC 4: $BBIA (47630) 














ae 





Pep a 
89600, which is easier to reseaber, asy be used instead, Mick Green of Comacdure 
WK pointed thin out. 
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TAB( SPCC ’ : 




















OTHER 
Validate parameter (0-255]} |] Subtract 10 
| validate. | Return. Put into the X-register. repeatedly 
Check for parenthesis ‘}', } |] from cursor 
String position till 







Expression 4, y negative. 












Subtract 
cursor 
position 


hange sign 
i.e. 2's comp- 
lement) 


Convert 
numeral 
Inte ASCI! 












string In 


buffer. Negative 
result? 
Print 


string+ 
apece. 


Get 
next 
char, 


End of print 
statement? 











Cancel buffer. 
Print CRLF and 
return to BASIC 







End of orint 
statement? 





Return to 
BASIC, 








FLOWCHART OF CBM BASIC'S PRINT STATEMENT PROCESSING 





Totes: (1] After « colon or end of line, CRLF in aiways printed by BASICe 1 and 2. 
BASIC 4 however (toma the other exit point, checking for devicu number; 
eo that if location 916 (16) is <¢ 124, C.Rtn. 18 output alone, without 
Line Feed. This was introduced to siuglify writing to dinks and tape, 
Previously, PRIMT#A,X9$;CHAS(19}; wae noceasary. With BASIC 4, PRINTS, 
X$ ie fine (and i@ also compatible with the aarlter form). 

(2] TAA{, SPCC, and comma have slightly different effects when printing, 
depending on tha contenta of 3 (BASIC 1), 14 (BASIC 2), and 16 (BAAIC 
4). TE thie location holda asro, the skip effect is achinved by Ch 
cursor right characters, and CALF is printed at the eid of the lines; 

@ non-sero valus printa spaces instead, and no automatic CRLP, #0 non- 
CBM equipment aay be ueed. In quutes mods, ship shows an reverse |. 
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PRINT+ 


BASIC output command 


PURPOSE: Evaluates and prints string expressions and numeric expressions to an 
output device, usually printer, disk, or tape. The appearance of the output 
is kdentical to that produced by PRINT, except for possible differences In 
interpretation of special CBM editing characters. 


Syntax: PRINT# arithmetic expression (, expressions to be printed in format 
identical to PRINT]. The comma is a separator to make unambiguous such 
statements as PRINT#3,3 and PRINT#33. There must be no space between 
'PRINT' and '#', because this will interpret into two bytes ('PRINT' and ‘a' 
separately, not the single 'PRINT# token.} ~- Except in BASIC L! 

Finally, the expression immediately following '# must conform to two criteria: 
after evaluation and rounding-down if non-integrai its range must be 1-255; 
secondly, a file with this number (‘logical file number’) must be open. 


Modes: Direct and program modes are both valid. 


Examples; 100 OPEN 4,4 : REM CHANNEL 4 TO PRINTER OPEN; NON-CBXM PRINTER... 
1000 PRINT#4,CHR$(12) “PRICE LIST no."N3" page” PS 


100 OPEN 1,4,1: OPEN 2,4,2: REM 2 CHANNELS TO SAME CEW PRINTER... 
110 PRINT #2,°$9$3939.99" > REM CBM PRINTER FORMAT USES SEC.ADDR. =2 
1000 PRINT#1, DOLLARS : REM OUTPUTS IN DESIRED FORMAT (EG. $24.00) 


2000 PRINT#4,;; CLOSE4 : REM CLOSES WITHOUT C.ATN. (WITH PRINT CMD) 


10 OPEN 5,8,5,"L: FIRST FILE,SEQ,W" :REM CBM DISK EXAMPLE 
20 FOR J=1 TO 20; PAINT#5, "RECORD NUMBEA"J: NEXT :REM BASIC 4 


8000 PRINT#4, XS¥$Z9; CHR$(13);; REM BASICS 1 AND 2 NERD THIS 


These examples are confined to printers and disks only, but in practice of 
course files can be opened to tape, screen, or any IEEF device, CBM or 
otherwise. The first sets of examples contrast the way 4 non-IEEE printer 
(a.g. Qume) is controiled with CBM‘s IEEE device. Assuming a hardware 
interface exists to convert IEEE to (say) RS232, the file can be opened as 
uaual, and controf characters sent to the printer to alter its spacing or line 
separation or other feature, or, here, send a form feed command. CHM 
printers rely on the [EEE's secondary address feature to control the printer 
In addition to controi characters, and the example shows how PRINT# can 
distinguish between several files open at one time. Line 2000 shows how a 
flle ia closed if CMD and PRINT were used: see note [1] on this. The 

final examples show another complication involving disk files (not tape, and 
not BASIC 4), The eartier ROMs wrote linefeed characters to disk, afier the 
carriage returns which are used as record separators, Consequently, data 
when read back from disk started with an unwanted linefeed character, and 
this CHR$(10) could be suppressed only by printing CHRS$(13), l.e. return, 
at the end of @ record. Footnote I of the PRINT statement flawchart amplifies 
this is somewhat greater detail. 


Notes: (1] PRINT#H, PRINT, and CMD are intimately related: 

PRINT# + SEND 'LISTEN'/ PRINT/ SEND 'UNLISTEN’ 

CMD = SEND 'LISTEN'/ PRINT 

PRINT = PRINT 
Thla js why PRINT#,;: and CMDn,;: are opposites. Eech prints nothing, 
then PRINT# unliatens the device, while CMD lenves tt ilatening, It ts also 
the reanon for Ilne 2100 in the examples; before closing the fie, if CMD waa 
uaed, PRINT#,;: has the function only of unllstening the disk or printer. 
Note that PRINT#@ ie better than CMD and PRINT with CBM printers, which 
aro apt to turn the ‘Tisten' off. In practice all this is caaior than It may appear 
to ba; Ht Is not essential, In gettlng data stored and printed, to appreciate 
ell the fine points of thease cummanda, 


£21 Some printers (not CHM) won't print out thelr internally stored buffer 
until a carrsge return (CHR #(13)} hae been recelvad, Earlier data ia thrown 
awey while it waite for thia to happen. OPEN 4,4: FOR Jeol4 TO 265: PRINTS4, 








ne i cee a 
aA crahe RIE 
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+; NexT may simply do : 
aay one its impassivity to oversight of this simpie fact. eee 
i i itted is tha , 
roblem if carriage returns are omi iS 
Shick td See erer imege of PRINT# a3 pr Aachanenionge Bi wolay tis egg a 
fely aceept strings of only 80 characte : eg 
pattie aida athee foster: go INPUT# will take in a composite string 
possibly with a ?STRING TOO LONG ERROR. 


Abbreviated entry: pR (includes # * 


Token: $98 (152) m 
chine code instruc 
: for this command has ory two mact 
ala vel pe Pear eats CMD, which carries out the validation Lcd Sedans 
wb aan sets the output device, and me. Eee eras the See 
i d routine unlistens the fie @ I L ‘: 
Toe eee waynonrd and screen. All of this helps explain the interconnec 


edness between PRINT#, PRINT, and CMD. 


ROM entry points: 


#: BASIC 1: 3COTF (51583) 
parse BASIC 2; $C983 ($1595) 
BASIC 4: $5485 (47752) 


BASIC 1: $C9CE ($1662) 


nothing. An apparently unresponsive printer 


? 
STINE: BASIC 2: $CODE (51678) 
BASIC 4: $BADB (47835) 
ARSTONE SASIC 1: CADE (51926) 


‘ ABT (51893) 
DEFAULT BASIC 2: +. 
DEVICES: BASIC 4; $BBR4 (48052) 
ee 


ee a TT 
the line will show PAINT#@ but give 


Telit ion # lw used, om Listing 

. 
fst a de Sn oe interpreter ‘seee' PAINT #, shich means 
TRYNTAX ERROR on running, oad on auch @ line and Return preased, the 


Rothing, BUT 1f the cursor is poaitia 
correct aeaning of PRINTS 


te taken in with the bine, P shift-® is etapler. 


Sagara eEnnD Er i a iiiceninsaieteinetesien eammieiies mada edehidneainnemn ania i t 
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PRINT USING 


Output command unavailable directiy in CBM BASIC 


PURPOSE: Prints data, often numeric, in s format specified by the program. 
Currency signs, trailing zeros, * or - signs, commas, ‘CR’ if a quantity is 
negative: these are alt typical features of formatting commands. Strings 
usually pose fess of a problem than numerals. 


5: BASIC keywords 


Versions; COBOL, a major business language, set a standard which most other 
formatting commands derive from. Its ‘picture’ clause enables the programmer 
to position the decimal point and insert spaces and commas within numerals, in 
addition to the features already mentioned. Thus, PIC $Z2Z2,22Z9.99CR causes 
-1234.5 to be printed as $ 1,234.50CR. The IBM 8000 series of desk-top 
machines and the TRS-80 use a similar notation, except that 9, which in 
COBOL prints a compulsory numeral, is replaced by #. Commodore's printera 


enable one (only) format to be pre-defined, and the formatting field is nearly 
pure COBOL.* 


Users of CBM printers apart. there is a constant demand for routines to format 
the output both onte the screen and to hardcopy and disk file, Hoth 'Diskpro’ 
and 'Commando’ include a formatting command. It does not validate its input 
completely; it is possible for oversized strings to be printed wrongly. BASIC 
versions have been published, some of them ludicrously long. For such a 
useful command, this can be rather discouraging. In the hope of improving 
the situation I present on the next few pages details of a relocatable machine 
code formatter which is relatively bug-free. 


Notes: The print routine can be called by SYS 47778 in BASIC 4 (and SYS 51622 
in BASIC 2, SYS 51609 in BASIC 1). This allows for string and numeral ex- 
pressions, TI, TAB( and SPC{ and so cn. For example, we may set PR=47778 
so SYS (PR) 8*9"Hello” prints ’'72 Hello’. In fact this entire routine, the main 
parts of which are very compact, can be moved into RAM and modified there. 
This ig not however the way the following routine operates; it uses a 5YS 
call followed by the numeric expression to be printed. This one value alone 
is formatted and output." The central piece of cade is this (BASIC 4): 


Jaz $BD98 ; input and evaluate any expression from BASIC 

J82 $CF93.; Convert contents of accumuletor#l into ASCII string 
JER @xxxx ; Code which processes the atring, bel¢ to $0100 ff. 
JSR $8B1D ; Print string using A (iow), ¥ (high) pointers 

RTS ; Return to BASIC 


The idea is simply to print the number in the way it would in any case be 
printed, but in addition to Insert a piece of code to edit the output buffer 
from which the string is printed. The actual processing ia controlled by 
several pokes, to contro! the type (decimal/integer), the desired string 
output length, the number of decimul places (where applicable), and fiiler 
characters. A leading character is sciectable for positive numerals only. All 
thla should be made clear by the examples, 


wee . 








+ 
CME printers are noted Cor puge in their 20Ms, so the actual output may not 
tlvays be an expected. 


>The Perenthesea are used purely to neparate SYS (PR) from the subsequent data. 

Tt 19 Perhaps worth pointing out that wlsunderstaoding of the pyntex can cause 

bugs. Thue: sys (PA) 40 prints a formatted veraion of 48; but SYS PA45 inputs and 

*Veluates PR4S, which the translater conalders to be the suse ae PR, so sero will 

cone And #Y5 PR(43) eveluates the 45th element of array PAC), If this erray 
Sta; if not, 78AD SVBACAIPT RAROR will be printed. 
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RELOCATABLE BASIC LOADER FOR “FRINT USING’ TYPE ROUTINE (NUMERAL FORMATTER) « 


0 DATA 1,852,.32, 162, 0,221, 0, 1,240, 6, 232, 224, 12, 208, 246, 24, 96, 169, 69, 32, ~162 
L DATA 176,90, 173, ~166, 240,94, 179, 2, 1, 20B, 11, 172,-165, 169, 48, 153, 2, 1,136 

2 DATA 208, 250, 169, 46, 32, -162, 168, 144, 2, L60, 48, 169,0, 32, ~162, 152, 157, 0, 1, 169 
4D DATA 46, 32-162, 172,-164, 232, £36, 208, 252, 236, -165, 176, 93, 172,-165, 16960 

& DATA 153, 1,1, 189,0, 1, 20!, 32, 208, 3, 169, 32,234, 153, 0, 1, 202, 16, 6, 173, ~163, 136 
5 DATA 16, 244, 136, 16,231, 169, 9, 133,97, 160, 1, 132, 98, 96, 169, 0, 32, ~162, 144, 240 
6 DATA £38, 168, 173, 2, 1240, 9, 169, 46, 32, ~162, 144, 2, £38, 168, 152, 170, 202, 16, 18! 
2 DATA 9, 32,159, 206, 32, 233, 220, 32,-148, 32, 28, 202, 96 

8 REM 

9 REM 

10 PRINT" {CLEAR} (REVS] ROM2 RELOCATING “PRINT USING’ ROUTINE " 

20 T = PEEK (52) + 256%PEEK (53) : REM T 1S CURRENT TOP OF BASIC MEMORY 

30 L = T - 166 : REM PROGRAM IS 166 BYTES IN LENCTR 

40 FOR J = L TO T-l : REM LOOP PLACES ROUTINE IN TOP OF AVAILABLE MEMORY 

30 READ Xf: IF XX<O THEN Y = X24 T: XX = ¥/256 : Z= Y= XL*256 ¢ PORE J,2: IaJ+1 
60 POXE J, XZ 


70 NEXT 
100 XZ = 1/256 : Z = L = X2*256 : REM WILL BE RI & LO BYTES OF NEW TOP OF MEMORT 


110 POKE 48,2 : POKE 30,Z : POFE 52,2: REM SET LO BYTES OF MEMORY AND STRINGS 
120 PORE 49,X%: POKE S51,X%: POKZ §3,%%: REM SET Hi BYTES OF MEMORY AND STRINCS 


123 MEM 


124 REx : 
125 REM ### NOW PRINT OUT INSTRUCTIONS FOR USE, WITH ADDRESSES, ONTO SCREEN ##¢ 


130 PRINT "(DOWN]SYS (" ; L¥#153 5 ") FOLLOWED BY ANT NUMERIC 

131 PRINT “EXPRESSION PRINTS THE FORMATTED VALUE, 

132 PRINT’KEEPING THE CURSOR ON THE SAME LINE. 

133 PRINT"DECIMALS ARZ TRUNCATED; ROUND TO NEAREST"; 

196 PRINT'WIETH +. [0] [0].--[025 IF REQUIRED 

140 PRINT" (DOWNJPOKE” ; L ; “{L&FT],1 FOR DECIMAL, @ POR INTEGER 

180 PRINT"PORE” ; L+L ; "TOTAL LENGTH OF OUTPUT - 1 

160 PRINT"POKE” ; L+2 3 “NUMBER OF DECIMAL PLACES 

170 FRINT"POKE” ; L+3 ; “FILLER CHARACTERS 

180 PRINT"POKE” ; L+98; "LEADING CHARACTER WHEN +VE 

190 PRINT’ (DOWNJSAVE FROM"L"TO"T-L . 

700 PRINT” {$"";:COSUB500: PRINT” TO $;:L=T-~1:GOSUB 500; PRINT} 
210 PRINT’ [DOWNJSET UP WITH LENCTH 9, 2 DECIMAL PLACES, AND LEADING SPACES. 
250 END 

497 REM 

498 REM 

499 REM #7 ONE LINE DECIMAL TO HEX CONVERTER ee 

$00 L=L/6096: FORJ=1 TOS: LA9L ILS-CHRS(4B4L2=(L2>9) 87): PRINTLS; :Lal6*(1,-L%) NEXT ASTURA 


READY. 


aeoeese§=§=6BARIC ¢ DT OOO8E 
7 DATA 0,32, 152, 180,32, 147, 207, 32,-148, 32, 29, 187, 96 
10 PRINT "[CLEAR|(R¥9} ROM4 RELOCATING ‘PRINT USING‘ ROUTINE “ 


anegaee § §=BARGIC 1 eeeenes 

7 DATA 0,34, 184, 204, 32, 17S, 220,32, 148,93, 38, 202, 96 

10 PRINT “[CLEAR] [AVS] ROML RELOCATING ‘PRINT USING’ ROUTIHR ” 

90 T = PEEK(134) + 256*PEEK(135) > REM JT I8 CURRENT TOP OF BAHIC MAMORY 
110 PORE 120,22 : POKER 192,2: POKE 134,2 

120 POXE 292, %%: POME 133,X%: POXE 136,23 


ware 


2 Ree te eT 


8 ae REE 8 TEI Se RT REE EGS MRT oe OS OE LO AD ET ARPT NOT aT ASP RM RRENERP TRON est 0, 
? 7 


Programming the PET/C8M -T2~ 5: BASIC keywords 


BOM4 RELOCATING 'PAINT UBING' ROUTINE 


8Y3 ( 32755 ) FOLLOWED BY ANY NUMERIC 
EXPRESSION PRINTS THE FORMATTED VALUE, 
EREPING THE CURSOR ON THE SAME LINE, 
DECIMALS ARE TRUNCATED; ROUND TO NEAREST 
WITH +.(0)(0)...[0}5 IF REQUERED 


POKER 32602,1 FOR DECIMAL,O FOR INTEGER 
POKE 32603 TOTAL LENGTH OF OUTPUT ~ 1 
POKER 32904 NUMBER OF DECIMAL PLACES 
POKE 32605 FILLER CHARACTERS 

POKE 32700 LEADING CHAHACTER WHEN +VE 


SAVE PROM 32602 TO 32767 be 
{$7954 TO $7FFF) 


SET UP WITH LENGTH 9, 2 DECIMAL PLACES, 
AND LEADING SPACES, 





Thia example shows the effect of running the routine with e 32K ma 
containing mo machine-code in the top of memory. The screen eatbat aneuia 
appear exactly as shown. The routine occupies 166 bytes just below the 
screen RAM. Instructions, with the relevant memory locations, are shown 
and may he noted by the programmer for future use. Note that this routine 
is Protected in memory by the loader; if the program is stored and reloaded 
it will need to be memory-protected, and also of course must not overwrite , 
other routines. It is set up to print a string of length 9, in decimal format 
(so integers appear with ‘.00' at the end) and with leading spaces. So:- ; 


SYS (32755) 1/3 prints .33 
POKE 32604,4 sets the number of decimal places to 4; now 
S$YS(32755) SQR(12) = prints 3.4641 


POKE 32700,ASC("$") makes the leading charac 
‘ ter for aith : 
SYS(32755) £23+16 prints : $133,.0000 cea hea a 


Demonstration program: To make the POKEs more comprehensible, [ have used 
meaningful variable names. The actual POKE values will differ for non-32K 
mechines. Note the tast line of formatted printout, which is exactly what will 
appear on 4 screen or any printer. if an 'E' is present in the output, this 
pron does not attempt to procesa it, but prints it verbatim. : 

PANT«32755 : SWITCH=32602 : LNCTH=32603 : 0 - : : 
8 FOR Ss sae Gch atke AGS BREE 3: DECPT9=32604 : CHAR2 32605 ; LOGCHAR=32700 
KE BVITCH,O: POKE LNGTH,4: POKE CHAN, 42: PORE : 
2C POXE SWITCH,1: POKE LNGTH,7: POKE CHAR, 22: font Loocaan asi ae 
POKE DECPTS,4; BYS{PR)1/(1+J) am 
4 PORE DECPTS,2: POKE LOCHAR,ASC("$"): SYS{PR) 100% (1+3/106)4.005 
POEZ SWITCH,O: POKE LOGCHAR,32: POKE LNGTH,7: SYS{(PA}J#J*J 
SO PAINT * ";: POME SWITCH, 1: PORE LOGCHAA,48: POKE CHAR, 46: 
BOYS (PR)SQA (ABS (i) } = 
60 NEXT 
se-10 -.1111 $96.00 -1000 00003.16 
see*Q 1.0000 $100.60 G 00006.00 
#410) 0909 $110,006 1000 90003, 14 
#9920) «=. 0476 $120, 00 ago 00004, 47 
#0030) = £0332 $130.00 47000 0006.47 
#0940) 16243 $140.00 840900 00008.32 
se¢5D) | 0198 9150.00 125000 009007 .07 
#9960) «©0163 $140.00 216000 NOUDT. 74 
eee70 10140 9170,00 343000 00008. 36 
oeeaQ)= 6,012) 9180.00 5812900 00008.04 
@ee90) «=.0109 9190.00 7205000 onode. 4a 
*°100 9.0009901E-03 $200,00 1N00000 00010. 60 


READY. 
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READ 


BASIC program date Input command 


PURPOSE: Reads data stored In DATA statements. Each REAO fetches one item 
of data and assigns it a variable name. Originally this command was the 
primary means by which a program obtained its data, which the machine 
accepted from punched cards. 


Syntax; READ must be followed by a variable, or 4 list of variables separated by 
commas. These may be integer, string. or numeric, and can be arrays. If 
the type of variable does not match the corresponding DATA, this can be 
detected only at run time, and will cause a type mismatch error. 


Modes: Direct and program modes are both valid. Direct mode requires the 
presence of a program containing data statements in memory. otherwise an 
* SOUT OF DATA ERROR message appears. (This is what happens when 
"READY,' is under the cursor and return ts pressed). 


Examples; 4% DATA 154: READ X: DIM X$(X}: FOR J=l TO N: READ X$(J): NEXT 
Where the total amount of data is not fixed, a routine like this may be 
valuable: the first item of data, which will require periodic updating. holds 
the number of current data items; an array is dimensioned with this number 
and therefore capable of holding all the items, finally, the data is read 
directly into the array in a loop. 


SO READ MC%: IF MCX%<O THEN ADDRESS=MCR4T: HIG=AD/256; LOG=AD-256*H1% 


This example also shows how apecial values can be used as indicators that 
speciat procesaing is required. In relocating loaders, most machine code 
bytes are straightforward POKEs; only absolute addresses vary with the 
situation of the code. A minus sign, holding the difference between (say. 
as hera) the top of memory after relocation and the position within the 
code, is @ signal to compute the low and high bytes needed. 


FOR L«1 TO 10: READ 23: PRINT 1$: NEXT 


This direct-mode line reads the next 10 data itema from the stored program 
and prints them in a column on the acreen. 


Notes: [1] This routine shares the ROM routines of INPUT and GET, and hag a 
lot In common with them. The statement READ AA%,B,N$(6},C(20) is valid, 
end provided that the DATA is stored to correspond, will execute success~ 
fully. If it is not, a type mismatch error will be printed; this is caused by 
something tike READ X when the data pointer indicates, say, NW3, READ 
with an integer variable ruunds down floating-point numbers. Generally, 
READ X$ will give no trouble, and will read any data; but it can be good 
to check the number of numeric data items by reading Into a numeric 
variable. No evaluation is carried out by this routine, any more than GET 
or INPUT; DATA 15*2.25 can be read only as 48 string. 


[2] Mismatches cause SYNTAX ERROR, but In the DATA statement line. 
A similar bug occurs when 6 function definition is Incorrect; in this case 
too the associated Hne in wrongly flagged as eontaining the error. 


Abbrevisted entry: rz Tokan: $67 (135) 

Operation: The elaborate routines shared by GET, GET#, (NPUT, INPUT# and 
READ are distinguished within the routine by fags: a special location 
($08; $62 In BASIC 1) holda 4$98 for REAG, #$40 for GET, a$u0for INPUT, 
Thus READ Is signalled by the N bit, GET by the ¥ bit, and INPUT by 
the Z bit. Also two variable locations check for mismatches: $07 how ASFE 
for a string, #300 if numeric; $04 han #340 for an Integer, #300 for floating 
point. ($5E, $5F In BASIC }). READ uses a routine wilch acuna BASIC state- 
monte - not lines - searching for DATA tokens, All tha ROMs procesa 
thia routine In roughly the aame way, 


ROM entry pointe: pasici :$Cag4 (62004) BASIC2: $C807 (61076) BASIC4:43BC02 (48130) 


ey 


See eee 


Niggas ee cee ee regs “ev 
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REM 


BASIC remark command 


PURPOSE: Permits comments to be included In BA 
SIC programs, These comment 
can in general be LISTed with the i lia 
Sing exteutlce, progeam, but are ignored by the program 


5: BASIC keywords 


aynten oe eee Be followed by any characters, Including :. which In this case 
nection as a statementseparator. Ev hi 
the hestline a icrered P. erything after REM and before 


Modes; Direct and program modes are both valid, 


Examples: 7000 REM “** MAIN CONTROL LOOP eee 
7003 GOSUB $1000: REM LOWER MEMORY TO ALLOW ROOM FOR 2 BUFFERS 
7006 GOSUB $9000: RFM PRINT INSTRUCTIONS AND AWAIT SPACE BAR 
7009 GOSUB SO000: REM SET UP NUMERALS, ARRAYS, STRINGS, VARIABLES 
7012 GOSUB $7000: REM PRINT SCREEN FON PARAMETER INPUT. 


30000 REM 
e* MOVE TO TOP OF KEW PAGE AND PRINT TITLE *4 


NPS="" :FORLS=59T062 : NP$=NP$+CERS (PEEK (LT+LS)}) :NEXT : REMSUB9O:0%(1)=NPS 


The first example shows the most common use of remark i 
the functions of a program clearer than they would tinicwibe Bae Bik 
of REM statements may be written before a program or subroutine givin 
very detailed explanations of the working. See elsewhere in this book for 
exampies, Line 30000 illustrates one of the many tricks available with REM 
which rely on the fact that syntax after the REM is unimportant. Here 2 : 
carriage return characters have been POKEd into the comment statement 
which therefore prints its message onto a new line. REM is sometimes usable 
in direct mode; the last example ig a line taken from a program, with its 
Unenumber erased so it will run in direct mode; the REM near the end of 
the line prevents execution of an unwanted part of the code. ° 


Notes: [1] LIST may produce stran 
ge effects with REM. Unshifted al 

after REM appear as ordinary text, but shifted Uierectre (one cing 
Quotes) are interpreted as tokena and converted into reserved words ,often 
expanding the LISTed line a great deal. Other characters - clear aseeehe 
form feed,cursor down, and so on - can, as we've geen, be incorporated 
inte comments: for programa to do this, see Chapter 2. SYNTAX ERROR 
is caused on LIST, and the listing will stop, if eshift-K {HASIC 1) shift-L 
(BASIC 2), or CHRS(219) In BASIC 4, are included In a REM statement 
The 8032 keyboard does not possess chr$(219), which is shift-[(. : 


(2] If your intention ls to remove remarks f 
rom the finished program, it 
hand be worth reserving linenumbers (aay) ending 6-9 for REMa, and never 
ranching to these lines with GOTO or GOSUB. : 


Abbreviated entry: None 
Token: $8F (143) 


Operation: This routin 

: 1 scenes for an end-of-ling zero byte; when this is f 

maces register holda the number of bytes offset from the aacrise CRUE 
pont ion, Y¥ is transferred to the accumulator and added to CHRGET. so 
Proyram control is transferred from KEM to the next BASIC Ine , 


This routine is embedded in the middt 

: e of IF, ao that, should di 
ee: the equivalent of REM Ia carried aut ~ le. the Seance af tre 
aed ar ariel pee fs a similar routine, except that, in addition to the 
he cast ae » It accepts a colon; ao lt skips to the next statement, nat 


#Om antry points: 
BAATC 1: $9099 (01953) BASIC 7; OCRAS ($1267) BASIC 4; $BECE (47302) 
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RENUMBER 


BASIC system command unavailable directly in CBM BASIC 


PURPOSE: Changes linenumbers of & BASIC program non-manually, either to give 
an improved appearance or to permit additional lines to be inserted. Other 
reasons may exist, too: a range of linenumbers (say, ali over 60000) may be 
required to permit successful appends; @ program containing very low line 
numbers runs (slightly) faster than otherwise; and $0 oft, 


Versions: Many veraions of RENUMBER exist. At the time of writing none has ail 
the features required by 4 professional utility. This is odd, since for 
example Apple has had a good renumber routine for years. The earliest 
versions include J Butterfield's BASIC program and Bill Seiler's machine 
code routine.* Later, Toolkit included a routine similar in effect to Seiler's 
which renumbers only in constant increments. (So lines typically emerge 45 
100,110,12¢,...). Eventually, so-called '4-perameter' renumbers were 
written, to use a format lise this: 

RENUMBER 999, 1500, 1000, 10 
which would convert lines 999-1500 into 1000,1010,1020,... Ideally a renumber 
should also resequence, so that for example a subroutine could be shifted 
to a new position in a program. None seem to be svailable that do this. 


Operation: This command is more difficult to program than may appear at first 
sight. The problems lie in modifying the references within fines. As this 
short program shows, there ig no problem in changing the linenumbers 
themselves: 


$9999 REM**® TINY RELOCATABLE RANUMBER ** 
60000 Au1025:B=256:PRINT'LO/HT LINES, NEW START & INCREMENT: ": INPUT L,H,5,1 


60005 FOR RO TO SE4:1F PEEK (At2) #38 PEER (A+3) <LTHENA=PEEK (A) +B*PEEK(A+L)? NEXT 
60010 FOR R=OTOSES: XeStRet: LF Aw) OR PERK (A+2)+B*PEER(A+])>A THEN END 
60015 POKEAt3, LNT(X/B}?: POKEA+2, X= (INT (X/B) ) *B: A=PEEK(A)+B*PEEK(A+1): NEXT 


BASIC holds Hnenumbers as ASCII strings, 80 these have to be sought and 
changed. At least two passes are necessary, the first to store current 
linenumbers, the second to change references. Since GOTO 5000 may be 
renumbered GOTO 10000, lines must be expanded to accommodate extra 
bytes, (Some Inferior routines require lines all to be written with five 
figures, GOTO 01000 style). The syntex generally has to be assumed to 
be correct. IF X=0 THEN 10=X is ayntactically wrang, but might be renumb- 
ered as though 10 were a linenumber. Some instructions may contain jine 
references which only the programmer can deal with; for example, SYS or 
USR commands/ functions, or DATA statements, or computed GOTOs and 
GOSUBs written to include true computed destination lines. 


These esoteric problems aside, all renumbers need to deal with: 


l. If ... THEN llnenumber. 
fi. GOTO Iinenumber and GO TO lknen 


ili. GOSUB linenumber. 
iv. ON ... GOTO and ON ... GOSUB have a list of lines to be changed. 


vy. LIST with optional linenumbers and RUN with optional number ace the 
only other commands which include Unenumbers among thelr parameters. 
RUN Unenumber is more important than LIST. 

vi. If the destination line doesn't exiat, this must be flagged as an error. 

vil, The renumbered lines must be checked for overlap with original lines. 

vill. The renumbered lincs may be outaide the valld range. 

ix. Possibly the new program or one of (ts Ilnaw may become too bong. 
Fortunately this Is very unlikely. 


umber. (In BASIC>1 these differ), 


er et 
*glightly aisprinted in Micro (first line should hold T#0), and in PET User Notes 
{Nov-Dec. '78), reapectivaly. Others, ¢.£. IPUd, have their own versiona, Power, 
Diek-0-Pro, ate. have four-parameter ronumberere. 





spew eee: 


ne. 


eee ay 


ears 


i a oa 


oo 


| 


Programming the PET /CBM -tat- 


RESTORE 


BASIC data command 


5: BASIC keywords 


PURPOSE: Resets the data poi 
pointer within a program so that data stored 
poarem ts READ from the eartiest DATA statement. Data a aad ag 
DO sequentially until 2 further RESTORE. 


Syntax; Restore hag no other parameters. 
Modes: Direct and program modes are both valid. 


Examples : 15000 REM RELOCATABLE DATA ROUTINE FOR BASHTOTAL 
13910 DATA HASHTOTAL, i69,0,141,202,3,162,1, 160,20 


15050 RESTORE: FOR L=OTO9B9: READ 
: = H X$: IF X$<>"HASHTOTAL” 
16060 FOR L=971 TO 1018: READ LS: POK2 L,LS: NEXT eur 


2000 READ X$: IF X$s"ENDY THEN RESTOR? 


a a tines 15000-15060 demonstrate a method to ensure that DATA and 
Pia reba debate igh deel correctly. All that’s needed is a name 

» included at the start of the data, which act 
and can be searched for. With only a few routines, this matheds ie et 
necessary, But with a great many it may be valuable. 


Line 2000 ia an analogous, but diffe i i 
1 rt rent, situation where th i 
Libel ie required fo be epee Sereclag Perhaps in «a games Siopranl palit 
es or odjects. If the last item of data is EN 
each READ tests fi i aa Tur 
ren CnRon, s for it as line 2000 does, there will never be an 20UT OF 


Notes: [1} NEW, RUN 
: , , and CLR cal! RESTORE as an automatic par i 
. . t f 
ne RESTORE in direct mode followed by RUN therefore dace 
ple ee by coro I own would not do. However, RESTORE in direct 
inenumber allows separat 
program variables, and can be useful sotiatlnee, Pe, eer ee 


(2) It ia possible to set the poi 
} pointer, not to the start of BASIC, but t 
peat at other items of DATA. See G.Yob's Creative Competing article ba 
3 theme, also in Printout of Oct. 1980. 


Abbreviated entry: reS 
Token: $8C (140) 


Operation: Dec 
7 rements and stores the contents of ($28) - star 
1 - t of - 
ae ae - DATA pointer. In BASIC 1, from ($7A) into Vat 
vodtite tear rebrand ponte might fike to compare thia with a 
r A a routine, fust after CLR, adds $FFFF 
Start of BASIC, saving 1 byte over RESTORE, which subtracts lL. as 


ROM entry points: 


BASIC 1: $C7OD (50057) 
BASIC 2: $C730 (80994) 
MAZIC 4: $B7B7 (47031) 
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RETURN 


BASIC command 

PURPOSE: Changes program flow of control to the statement immediately after the 
mest recent COSUB statement. These two commands therefore permit sub- 
routines to be automatically processed without the nced to keep a note in 
the program of the return addresses. 


Syntax: RETURN stands alone with no parameters, It may only be followed by 
spaces (these are optional) and must be followed by either a colon or an 
end of line. If no GOSUB corresponds to & RETURN - for example, when 
0 RETURN is RUN - the error message ?RETURN WITHOUT GOSUB appears. 


Modes: Direct and program modes are both valid. 
Examples: 10 INPUT L: GOSUB 10000: GOTO 10: REM TESTS SUBROUTINE AT 10000 


10000 L# (INT ((L- 008) /RQ)+1)*RQ: BEM RQ=ROUNDING QTY; .O1,.05,.50 bc 
£0010 PRINT L;: RETURN 


This example shows a test routine which allows the user to input any number 
and responds with the result of the subroutine's processing. Here, we have 
the first stage of a BASIC round-and-format routine which rounds up by an 
amount varying with parameter RQ. The next stage adds decimal points to 
integers, and generally tidies up, but the point here ja that the subroutine 
ia tucked away in a completely different part of memory, but the RETURN 
automaticaliy tranafera control back, to line 10 in thia cass. 


$0 GO TO 1000 

100 REM *«* MORE PROGHAM *** 

270 GOTO 1000 

300 REM *** KORE PROCHAM *** 

1000 REM SUBROUTINE WITHOUT A ‘cosuB' 

1010 REM *** PROCESS DATA WITHIN THE ROUTINE *** 
1100 REK GOTO 1007 GOTO 270? GO ELSEWHERE?? 


Thia second example is an attempt to explain the difficulty of having no 
GOSUB/ RETURN conmands. What Is handled effortlessly with these comm- 
ands becomes # probtem without them. 

Notes: {1] GOSUB and FOR share the same method of using the atack: data ta 
pushed on the atack In elther case, and the stack polnter ig left pointing 
to a token, which may be either FOR or GOSUB. This double use doesn't 
cause conflict unless certain combinations of BASIC are tried. This for 
inatance causes 9NEXT WITHOUT FOR ERROR: 


10 GOBUB 1000; NEXT J 
1000 FOR Je0 TO 10: RETURN 


Occasionally, @ FOR varlable may be erased like thia; but it ta an easy 
programming error to avold. 


[2] RETURN can sometimes be used in direct mode; for example: 
10 GOSUA 100: PRINT "RETURN" / 100 END. Thie 1s not often useful. 


(3) This command has no connection with the carriage return key, 


Abbreviated entry: reT Token: $aE (142) 

Operation: After validating the command, the routine to check POR and GOSsUB 
tokens ja called: @ Flug is net before entry to ahow that RETURN ja the 
command, not NEXT. FORKs are removed and $8 tokens looked for; If none 
{s found, ?RETURN WITHOUT GOSUB Is printed, When found, the HASIC 
Hnenumber and CHRGET polnter are recovered, ua they wera left by GOSUB. 
The routine now merges with DATA. So It aearenen for the next statement 
after the pointer; thus, ON K GOSUH 10,20,30:PFHINT X ..- RETURN causes 
the remaining llat of varlablon to be ignored; the colun, or $f no colon the 
and of tne zero byte, marke the point et which exevullon revommencea. 


ROM entry pointe: BAMICL:SCTCA (51148) BASIC: 9C7DA (B1169) BAAIC4; SBHHD (47197) 
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RIGHT$ 


BASIC string function 


PURPOSE: Extracts a substring, tonsisting of the rightmost characters, from a 
string. This function, with MID$, RIGHTS and the string concatenation 
operator +, is used In text and string processing in BASIC, 


Syntax: RIGHT &(string expression, arithmetic expression). The string expression 
must be vaiid, i.e, made up from atring functions and/or literals and/or 
string variables. Its length cannot exceed 255. The maximum value of the 
arithmetic expression is 255; the minimum value depends on the ROM 
BASICs prior to 4 will not accept a value of zero. BASIC 4 has been 
modified to accept zero, returning the null string with RIGHT $(X$,0). 


Modes: Direct and program modes are both valid. 


Examples; PRINT RIGHT$(“REAGAN", 4) +REN RESULT IS AN 
10 PAINT RIGHT9(" "¢6TRS(N),10) ; REM ANOTHER TAB( 


Bo REM ¢* W$ HOLDS TARGET WORD: G$=CGUESS LETTER 
i ; S$=STRING SO FAR 
100 FOR J=2 TO LEN(R$): S$=S$+"'-"; NEXT: AEM IF WS=HELLO, S$=----- 


300 FOR J=1 TO LEN(W9): IF G$—MID$(¥S,J,1) THE 
pple (W3,3,1) ¥ GOSUB 1000 


1000 S$=LEFT$(S$,J-t) + G$ + RIGHT$(S$,LEN(S$)-J): RETURK 
$1320 CC$a"{ DOWN] (RIGHT) [DOWN } [RIGHT] [DOWN] (RIGHT]" 


The first exampl eh s astralghtforward a lication of thia fu . 
e@ OW PP ks netion The 
second is another version of a TAB( style routine to help align pr inted 


The object of the third example, taken from a word game ('H an'), i 
to illustrate complicated string handling. [t is inv aviea thee aed 
string can be built up from existing strings by subdividing as far as ig 
necessary using MIDS (or the related LEFTS and RIGHTS functions} and 
putting the bits together with +. Line 1000 is a subroutine which does 
this, bresking S$ into two parts and connecting them with the correctly 
Fusened letter In between. [ff G$="L", the loop in Hne 200 calls subroutine 
60 twice, when J=3 and J=4. The result ia to convert "-----" into "--LL-" 
or "H----" into "H-LL~" or whatever, A similar scanning process can be 
Pca to many probiems in word guessing, multiple-choice questions 
oreign language quizzes, and so on, See Chapter 4, section 4.1.15. 


5: BASIC keywords 


Lastly, slnee atring functions may be used In PRINT agtutements, PET's 

yeti formatting characters can be processed in thls way too; line 51220 

pnt es CCS so that PRINT RIGHTS(CCS,2*N) moves the cursor diagonally 
nh the screen when N>0 and N<4, (tt’'a only a very simple example! ). 


Notes: 
tes: (t] This diagram should make the operation of this function clear: 


a xs-"[a [ri aii] tol 
mition from right: [6 (5 [4 [3] 2] 2) 


PRINT RIGHT$(X%,4) prints the four rightmost characters: RING. 


[2] RIGHT$(X$,N) can be replaced b 
i 2 y MIDS(X$, LEN(X$)-N+1). 5 
bias la the expression RIGHT S(X$, LEN(X$)-t) which Sanne hie. 
Hae e. from a string; MIDS(X$,2) performs the sama function. THASIC<4 
ean, a zero length puruncter; this conversion therefore can bo uneful In 
iding clumsy code. Line 1000, which fuils with BASIC<4, shows thin, 


Ab 
breviated entry: ri (Includes $) Token: $C9 (201) 


Oper : 
si ae string parsmeters ara recovered from the stack. Then a 2's 
ali ome d routine computers the length of the (original) string minus the 
pa Hie Thin vaiue (one byte) Is hetd in A. Now LEFTS (se cntered and 
aaing proceods as for LEFT$, axcept that A does not coniain #0, 


Pou 7 
try Polmts :BASICE: $0404 (54788) BABICA:9DHOd (64700) BASIC: SCHG2 (812994) 








Programming the PET/CBM ~124- 5: BASIC keywords 


RND 


BASIC arithmetic function 


PURPOSE: Generates a pseudo-random floating-point number in the range 01 
excluding the limits. RND can mimic statistical data in simulations, heip 
generate test data, and introduce unpredictability generally. 

Syntax: RND (arithmetic expression). The arithmetic expression may take any 
value within the valid range of floating-point numbers (+1.7E 38 approx,). 
Only the sign influences the result, not the magnitude. 

100 FOR J=0 TO 3000*RND(1} : NEIT : REM DELAY OF 0 TO THREE SECONDS 

200 N=70; FOR J=0 TO N*RND(1); ABAD X$: NEXT; REM READS 1 DATA ITEM 

100 FOR Jal TO @: P= PEEK(32809 + RND(1)*920):IF PEEK(P)=32 THEN 

POEE P,1764+3 : REM IF A SCREEN LOCATION IS EMPTY, PUT AVS 1-9 IN 

110 NEXT 

100 IF RND{1}«.1 THEN PRINT “A VERY GOOD MORNING TO YOU" 


Examples: 


O PRINT “[CLEAR}": 1333228: GOTO 10 

1 Jx-41:RETURN/2 J=-40: RETURN /3J=-39 : RETURN/4J=—1: RETURN 
5 J=i: RETURN/8 Ja99:RETURN/7 J=4G:RETURN/S J=41:RETURN 
10 ON RND(1)*a+t GOSUB 1,2,3,4,5,6,7,8 

20 M=I; I=I+s 

90 IP 1632768 THEN f=1+2000 


40 IF 1933767 THEN I=I-1000 
30 POKE 1,91: POKE M,32: GOTO 10: REM ‘BALL’ AND BLANK POKED IN 


The first and second examples use a loop In which the final value varies 
with the random number selected: this causes a random delay in the first 
example (usable perhaps in a reaction-time game) and the selection of a 
random string in the second, assuming 4 list of 70 data items exists in the 
program. (Usable in a foreign-words quiz or guessing game). The next 
example is a short program, designed to piace 9 values onto & 40-eclumn 
screen, at random, but ignoring the top and bottom lines. Still another 
line 100 follows, and this one has a one in ten chance of printing its greet- 
ing. Finally, we have a comparatively long program, which relies on RND 
to pick one of eight subroutines. (The slash marks are there to save space), 
It ja a simple version of a ‘random walk’. 


Notes: {1) RND generates determinate numbers, not 'random' numbers, if indeed 
these can exist. The sign of the argument (+,0,or-) affects the numbers 
computed. A speciat location holds the fast random number: at switch on — 
this has a constant put into it, and every subsequent call of RND reaets it. 
Any constant value is called a ‘seed’. RND(+ve) computes the next value in 
an infinite sequence. It Is tke taking the remuinders after dividing 10 by 7; 
the pseudo-random sequence 3,2,6,8.5,7.1. ... is formed and continues 
indefinitely. After about 45000 repetitions 1 have the Impression that the CBM 
series lose theie ‘randomness’ and become more predictable. If the seed is 
fixed, the subsequent random numbers can he repented; and RND(-ve) puta 
a functlon of the accumulator into the sred aren. So X=RND(-1): PRINT 
RND(1); always prints the sane value, and ja the start of a repeatabie 
sequence, RND(0) loadsa the floating-point accumulator from the VfA timers, 
two of which change at the same frequency 44 the chip (1 MHz), RNL(O} 
therefore is not repeatable. and makes a good seed value, ewever, it may 
not be suitable for repetitive progrumming: ivy it in the random walk, Alwo 
BASIC t doesn't work correctly with RNU(0), HND{-TL) therefore la a good 
function to use whan 4 non-repeatuble sequence ia atmed at, 


[2] A random number in the range A-B, excluding ihe exact end Ulta, Is 
genoratrd by: A> RNDCL)9(B-A). A special case tal + RNDC1}*2 which 


generates random numbers from -t to +1, For Integarn from At BR, 
AS + INT(RND(1}©(B-Aet) covers the range, Including both imita, 


ROM entry polnts:BASiC1:$DF45 (67167) BASIC2:90F7F (57213) BAMICA: 90239 (63801) 
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5: BASIC keywords 


RUN 


BASIC system command 


PURPOSE: Executes a BASIC program in memory either from the beginning or 


from eny linenumber. Previous values of variables are af) lost on RUNnIng. 


Syntax: RUN [(iinenumber]. The linenumber is optional. See also note {1). 


If a line of the specified linenumber doesn't exist, 7UNDEF'D STATEMENT 
ERROR is printed and nothing more happens. 


Modes: Direct and program modes sre both valid. 


Examples: RUN 


Notes: 


Abbreviated entry: rU 


:HEM CLEAR VARIABLES AND RUN 
RUM L000 : REM CLEAR VARIABLES AND RUM PROM LINE 1000 


These direct mode commands, as typed at the keyboard, execute BASIC. 


$000 INPUT “RETURN TO START"; YN$: REM APPEARS AS ‘RETURN TO START?’ 
$010 IF LEFT$(¥N$,1)""¥" THEN RUN 
10000 LOAD "NEXT TAPE PROGRAM’: REM RUN IS IMPLICIT 1N THIS 


RUN may be called within a program; all variables and arrays are cleared, 
so this is useful if restarting BASIC from scratch. Line 10000, which uses 
LOAD from within a program, implicitly RUNs the new program too. 


[1] When RUN is not followed by a colon or end-of-line, it is presumed to 
be followed by a line number which is evaluated by a part of the GOTO 
routine. The linenumber is therefore not completely validated (it need not be 
an arithmetic expression), Consequently, AUN X and RUN "PRG" are both 
equivalent to RUN 0. And AUN 25QQ is equivalent to RUN 25. 


[2] RUN does not load and run, like (say) Apple. The shift-stop key has 

this function. In BASICs } and 2, this key inserts the string "LOAD(RET- 

URN JRUN[RETURN J” into the keyboard buffer, which causes the usual tape 
loading sequence {o be activated, starting with the request to 'PRESS PLAY 
ON TAPE#'. BASIC 4 uses the atring "4L"*[RETURN Jrun(RETURN]” which 
loads and runs the first disk program. 


[3] Not ali RUNs share Microsoft's conflation of CLR with RUN. Some Sharp 
BASICs, when RUN, retain their old variables, so that CLR:RUN would be 
their equivalent of Microsoft's RUN command, Conversely, to run Microsoft 
BASIC without resetting all the variables requires GOTO linenumber. 


[4] If location 1024 (and end of line bytes generally) hold some non zero 
byte, RUN will stop with a 2SYNTAX ERROR. 


(5) If the end-of-program pointers are wrong, typically through loading one 
program from within another, RUN, either implicitly on loading or explicitly, 
May corrupt the program as soon as variables are given values. See OLD. 


Token: $8A (138) 


Operation: RUN elone sets GETCHR's pointer to the atart of BASIC-1, then drops 


into CLR, which erases data, resets the DATA pointer, aborta open files, and 
resets the atack; ft saves the top return address on the atack, which points 
to the RUN routine Itself. RUN lincnumber also CLRs, but without resetiing 
GETCHR; then finde the line, and enters the RUN routine os before. 


Progrems are executed by a foop which performs single statements, The loop 
haa thle structure: (lL) Test atop key, Cif) Store CONT pointer, ili) Test 

for zero byte: If found, either end the program, or update the stored current 
IInenumber and CHRGET, (iv) Gat the currant character, (¥) Execute one 
atatement, (vi} Start over at the beginning of the loop. 


The routine can ba rewritten by a programmer, excluding, for example, the 
faating for the stop key which la otherwlao performed before each atutement. 
Soma timanaving is poxalble in inlu woy, A faw fant RUN programs are on gate, 


ROM entry points: 


BUN EXYWORD:BASICL:OCT75 (61061) BAMICI: SCTAS CO1077) BASICA: 9BAOH (47112) 
BIRCUTION: BABIC1:SCOBD (60860) BAMICI:$COC4 (G0NN4) BABICA: SB74A (49923) 








Programming the PET /CBM ~t27- 3: BASIC keywords 
Abbreviated entry: sA 
Token; $94 (148) 


Operation: The outlUne that follows expiains how SAVE works. BASIC 1 is similar 
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SAVE 


BASIC system command 


PURPOSE: Writes ® consecutive block of RAM to an output device, usually disk 
or tape. Normally this Is a BASIC program, which Is saved with s mame for 
easy retrieval, although a name ts optional with tape. The converse process 
to SAVE is LOAD. 


Syntax: Identical to LOAD, inctuding the difference between tape and disk SAVE, 
where a name is compulsory with disks. Unlike LOAD,the secondary address 
has a purpose: a tape program, saved with secondary address 2, writes an 
end-of-tape dlock so the cassette won't read past it. If the device number 
ia 0 or 3 (keyboard or screen) ?DEVICE NOT PRESENT, rather oddly, appears. 
if a file of the same name exists on disk, ?FILE EXISTS ERROR will result. 

Modes: Direct and program modes are both valid. When using tape, SAVE ["NAME"] 
is followed in both modes by PRESS PLAY AND RECORD ON TAPE#} or 2. 
WRITING [NAME] also appears in direct mode only. (Unless the cassette was 
already running}. 


Examples: SAVE : REM SAVES THR BASIC IN MEMORY ON TAPE ft (NO NAME) 
SAVE “PROGOOS",2,2: REM SAVE BASIC AS 'PROGOOG' ON CASSETTE #2 WITH EOT 
SAYS "",8 : REM NO NAME ... GIVES 7SYNTAX ZHROR 


BAVE “O;PROG<5",8 ; REM SAVE ‘PROGsS" ON DRIVE 0 

BAYES "@0O:PROG",8 <: REM SAVE-WITH-REPLACE 'PROG' ONTO DAIVE 1¢ 
SAVE CHRS$(&)+°TEST AATE’+CHR$(146),1 :REM NAME APPEARS IN REVERSE 
12000 SAVE "1:TEST’+T!I$,8: REM NAME SAVED WITH UNIQUE TIME ATTACHED 


These CBM tape and disk examples are (i hope) reasonably easy to follow. 
The tape examples show a ful! default (equivalent to SAVE "",1,0) and an 
example which writes end-of-tape after saving the program. The disk examples 
show the slightly more complex syntax needed, including the optional disk 
drive number and the mandatory device number §. The string is aiso mandat- 
ory. The third disk example shows the 'gayve-with-replace’ variation of disk 
save, which avoids the “file exists error. This form of SAVE is however 
suspected to contaln a bug; use it at your own risk, The final examples are 
intended to emphasize the fact that the atring parameter is computed: the 
firat example has ita name saved in reverse text, the second is a program- 
mode SAVE which may be used to store successive verslona of BASIC during 
development of a program; the time parameter shows when SAVE occurred. 


Notes: (1] .8 “MAME”,01,0274,0300 and ,B "1:NAME",09,0274,0300 are cagsette #1 and 
CBM disk drive I verslona of machine-code saves from the monitor. These 
use almost exactly the same routine as SAVE and in fact the same result can 
de achleved within BASIC. Compu/think uses $8,1, "NAMB", "0274", "0300", 

With CBM BASIC, thls routine is necessary: 
BYS (62526) “O:HELLO",@; REM GETS THE PAHAMKETERS FOR NASE & OKVICE 
POKE 251, LO-INT(LO/256)*258: POKER 252,10/254: REM LOW ADORZSS IN (FB) 
POKE 201, HI-ENT(HI/254)°256; POKE 202,H1/256: RIM AIGH ADDRESS IN (C9) 
SYS 63140 ; REM ENTER ‘SAVE’ SLIGHTLY LATER THAN UAUAL. 


This version is BASIC 2: for BASIC 4, substitute 62589 and 63203 for the 
SYS addresses. Remember to make the end address a hyte longer than it 
should bo: CBM's stve excludes the final byte. BASIC [I needs 62515 and 
63153 ae SYS addresses, and (F7} and (E5) fur its low and high addresava. 


Chapter 13 discunaes other modifications of SAVE and LOAD. 


{2} There is no readback check with tape. If 'Piay' ln pressed, but not 
'Record', SAVE appeara to operate correctiy, but in fact nothing ia written. 
(3) BASIC 4 and BASIC 2 with 'Disk-o-Pro' hava DSAVE too (q.¥.) 


i te 
There seenn to be no definitive atatewent availabie on the buga in SAYR with 

Feplace, which saves to disk and erased the previous file of the sase nase, using 
the extra parameter '@’. Some commercial software does une it; some people evoar 


by it, others swear at 1t! GCHATCH then GAVE 1s anfest. 
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bP schema, but its detailed arrangement, and its working storage areas, 
er. 


GET PARAMETERS FROM BASIC. ST is set to zero. Locations $D1, §D3, $D4, 
and ($DA) hold string length, secondary address, device number, and, Uf 
the string is not null, a pointer to the start of the string in BASIC. Where 
these parameters aren't specified, string length defaulta to 0, secondary 
address to 0, and device number to 1, 


MOVE BASIC START AND END POINTERS TO (FB) AND (C9). BASIC'S 
pointers in ($28) and ($2A) usually hold $0401 and some higher value; the 
contents of RAM will be SAVEd between these two locations. The monitor's 
save with .S carries out the identical functions to these two routines, then 
entera SAVE at the next point: 


DEVICE NUMBER CHECK. A device number of zero or three generates a 
TDEVICE NOT PRESENT ERROR. SAVE “HELLO",,2 for instance does this. 
(These devices - in case you've forgotten ~ are the keyboard and screen}. 


SEPARATION INTO CASSETTE AND [EEE PROCESSING. Devices numbered 
1 and 2 @re cassettes, and are processed by a separate routine from IEEE 
devices 4-15, 


IEEE PROCESSING. 


SECONDARY ADDRESS/ NAME CHECK. Secondary address is set to #$61, 
equivalent to t, to enable writing to the disk directory. A string parameter 
of zero length is rejected with ?SYNTAX ERROR. (This provides incomplete 
validation, because a string "i:" or ":" may still! be sent}. 


WRITE NAME AND START ADDRESS TO JEEE BUS. Firstly, the string is 
gent character by character down the bus, after handshaking has been 
established. LISTEN plus the secondary address (overwritten so that it is 
always 1) are sent. (FB) is moved to (C7); this address Is used to load, 
compare and increment from now on. (C7) pointa to the current RAM location - 
being sent, (C9) holda the final location which is not sent. The low and high 
bytes of the start address, C7 and C8, are sent on the IEEE. (Then, when 
LOAD reverses this process, it knows which RAM addrega to store the bytes 
from). 

LOOP, SENDING SINGLE CHARACTERS ALONG IEEE BUS. The sequence of 
actlvitlea here is: (1) Compare address (C7) with (C9); if they arc now 
equal, exit without sending the flnal character. (il) Load the accumulator 
with the byte and send it; (lil) test the Stop key; (lv) increment the address 
in (C7); (¥) continue with loop - provided that (C7) did not increase from 
SFFFF to 30000. 


EXIT. Finally, LISTEN, the secondary address. and UNLISTEN are sent. 
CASSETTE TAPE PROCESSING, 


PREPARE TO WRITE TO TAPE. This sets (D6) to $027A or $033A depending 
on the device number, prints PRESS PLAY AND RECORD ON TAPE# 1 or 2, 
and, {fin direct mode, WRITING plus the optional program name, when 4 key 
on the cassaite ls detectad down. 


TAPE WRITE. The accumulator Is londed with ft and the ROM routine to write 
@ block (a ‘hender') called. #1 denotes a program. Then the tapo writo routine 
la ealled, and finally, if the socondary addrens was 2, another ‘header’ le 
written, thls time «Ith thea type character #5, Indicating #n end-of-tave block, 
See Chapter 8 for more detail on tha actual writing to tape. 


ROM entry paints: SAVE is a ‘kernel’ command; Ite jump address is SFFDS. 


BASICI:§FGQE (63134) BASICA: $FCQE (63134) BASICS: SFEDD (63197) 
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SET 


BASIC graphics command unavailable directly in CBM BASIC 


PURPOSE: Plots a ‘point! (in fact a small square) on the screen at a position 
determined by two parameters, which represent horizontal and vertical 
distances or X and Y coordinates from some starting point. 


Versions: Both BASIC and machine code versions of this routine exist for the 
CBM. BASIC usually is too slow. Some versions include straight-line plotting 
algorithms so that lines can be drawn without further enculation. The 
resolution is 30 by 50 for 40 column machines, 160 by 50 for 86 columns; 
this is useful, but not ‘high resolution’. (Many other machines have rather 
slmUar displays: the TRS-80 has 128 by 48, Sharp MZ30K 80 by 50, Sinclair 
ZX8! 64 by 44), Higher resolution in one direction can be achieved, for 
bar charts and similar diagrams, very simply dy plotting solid blocks and 
adding a final part of a block, which has a resolution of one part in eight. 
And approximations to sloping lines can be made with line segments, so 6 
curve will appear as a series of steps. (There is for exanpie a ROM chip 
called 'PicChip' which does this from BASIC). For more detail on this, see 
Chapter 9. The SET here is designed to plot double-density squares only 
with a fast machine-code algorithm. When called from BASIC it is still slow. 
This is because of the computing time which BASIC takes. However, it is 
perfectly usable, * 


Algorithm: ‘Micro' had an early version of this. Other publications, such as the first 
issue of 'Printout’, followed. The basis of the method is ag follows: 
Suppose we use the convention that horizontal (X) coordinates start at the 
bottom left of the screen with 0, and vertical (Y) cordinates also start at 
the bottom left, with 0, so 0-79 or 159 is the range of X values, and 0-49 
is the range of Y values. Taking 4 concrete illustration, suppose we wish 
to plot a white square at (1,1). The complicating factor is that there wiil 
be squares already plotted in the vicinity of (1.1), and since the character 
generating ROM only ailows one entire character to be changed, the plot 
has to take account of the character already present. [n our example, this 


is the character in the bottom left of the 
fatq} screen. We can do this with a look-up 
(2/8) table which arranges the screen graphics 
characters (16 of them are relevant to our 
tit——> purpose) in order determined by whichever 
quadrants are turned on: we assign an 
del 


arbitrary bit position to cach quadrant, The 

diagram shows how the quadrants are numbered, and the corresponding 
order, from lowest to highest, which the graphics characters take. 
Sia te PC) 
All we have to do is find the sereen ASCII value, find its position in the 
tadle, and ORA with 1.2,4 or 8; the result, looked up in Ihe table, gives 
the new character to be poked to the screen, Overleaf is a 40-column, and 
an 60-column, routine to do just this. Its operstion is explalned claewhere. 
To uae it, POKE 0,X coordinnte: POKE 1, Y coordinate; SYS 634 will plot 
a square. POKE 729,0 for a black square; any non zero value givey @ white 
square. The zero-page locations used ure theaa: 

$00:X coordinate; overwritten by X coordinate of screen, 0-39 or 0-79. 

$01°Y coordinate; replaced by screen pointer’s low byte. 


$O02<ecreen peinter's high byte. 
$04cremalnder after haiving both X and ¥ coordinates. The conflated 


remalnders are overwritten by 1.2,4 or 8. 
Note that $94 ja used by the NMI Iino; If you'r using non-maskah'e Int- 
errupta you'll need another xero-page (or other} location, BASIC 1 can 
auhatltute $30 near the end of the input buffer, 


Tat fa not optimiaed for apesd: a lookup tanie of ecresn-Ling start positions, for 
exeaple, could improve the running time, Sut with BASIC, the difference ien‘t great. 
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This monitor listing is eppropriate for a &@ column mochine running either 
BASIC 2ar BASIC 4 See delow for (i) B06 column modifications. (ii) BASIC 


Thi. 
gra; 


1 modificationa, and (iii} relocation. 


Incidentally, it is worth mentioning that the cheapest method of increasing 
the dot density - if you know someone with an EPROM blower - is ta use a 
character generating ROM containing the entire 256 2 by 4 characters. In 
association with a hardware device to switch between ROMs, this gives with 
an 80-column CBM a resolution of 160 by 100, about 2/3 of Apple's dot 
density. Since the 80-column characters are somewhat elongated upwards, 
this ought to improve the appearance too, The graphics character set does 
Include a 4 by 4 character, CHR${222) in one of the graphics modes. But 
it is easy to see that its entire character set equivalent can't be displayed, 
because 2N6=65536. 8 on/off alternatives is the maximum obtainable. See 


Chapter $ for further explanation. 
PC IRQ SR AC ER YR SP 
(41) 80-COLUI MODIFICATIONS: 


B780 £455 2C 34 3A 90 PA 
Replace the two tndicatead bytes hy 


027A AG 00 BS 94 AD 60)35 02 #$10 and #$A0. 
0283 AS DO C9 G0} 80 38 AS OL : 
028A C9 32 BO 32 A932 ES O1 pa tas She cbree: NUhs PY 


0292 46 00 26 94 6A 26 94 85 
O29A 01 OA OA 65 01 OA OA 26 
O2A2 02 OA 26 O02 EA_EA EA 5 (it) BASIC 1 MODIFICATIONS: 


G2AA 01 AG 94 BD(DD 02)a5 94 Replace all #3945 with #$590. 

0282 A$ 00 B1 O1 Az OF DD(E1 f2) 

O2BA 02 FO 04 CA 10 F8 60 AD ees RELOCATION: 

0202(DC_ 02) PO 06 BA OS 94 AA 

OSCA DO'08 BA. 40: PF 08 04° 49 os The three double-byte pointers aarked 


02D2 FF AA BO(E1 02) A4 00 91 

02DA 01 60 ape bo diy Suni, the end of the routine. The fourth 
02k2/TE Te IC RE FF RE 6c Quaarants poisgter loads the character which 
O2EA\7P 62 FC Ei FB FE AQ Jk Graphics, 


8S short demonstration program will plot a Lissajou figure, Note that non- 
Phics characters are ignored ~ i.e. no plot takes place there, 
1000 INPUT "TWO NUMBERS, E.G. 4,7°;A,B: POR J=0 TO 989 STEP . 2 
1010 Fe (1+SINCA*J)) * 40: ¥e (14C05(B*3))*25: REM OR 80 FOR I 
1020 POKE 0,X: PORE 1,¥: AY8 634: REM OR OTRER SYS VALUE 


1030 NEXT 
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38,8 3 ¥ - ~*~ owe 44 ee ir eee ee Ts 
Pr 
ioe ts ye aa Mar oy ae wate ee ets 
cy ee “Ee we” Sy ot” “hey me Ne Pid ee ote tee 
+ +e . " eee “ se Te hae See oe te 
Eat BP gh Ce gr a OT 
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3 * one veee wave oun we we oe 
woe Lda a9 os La al a ee . iJ 
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gn the listing point to the tables at 


determines the black/white awitch. Zach 
must be changed on moving this code. 
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SGN 


BASIC arithmetic functlon 


PURPOSE: Computes the sign of an arithmetic expression. SCN returns the value 
-1 if the expression is negative, 9 if zero, and +1 if positive, * 


§: BASIC keywords 


Syntax: SGN (arithmetic expression). The arithmetic expression must be valid and 
must evaluate to un acceptable value. 


Modes: Direct and program modes are both valid. 


Examples: 10 1¥ SGN(X) > 0 THN PRINT X; “IS POSITIVE" 
20 [F ABS(SGN(X})<>OTHEN PRINT X; "1S NON ZERO" 


FOR J=-100 TO 100; PRINT J, BCN(J), SON(J)*J, SGN(J)*ABS(J): NEXT 


DEP FN A(Z2Z) = INT(ZZ*100 + SGN(2Z)*.5} 
ON SGN (I) + 3 GOSUB 100,120,140 


SGN is one of the less exciting BASIC functions. It is closely related to 
ABS ,<,=, and >, in the sense that these functions and Operators can, when 
permuted, produce identical resuits. SGN(X-Y) for instance returns zero if 
X=¥, of if X>¥, and -! if X<¥. The two first examples show how SGN may 
be used. Although the logic is correct, the function is entirely redundant. 
Usually therefore this function needs to make use of the fact that explicit 
values of G or tl are returned if it is not to be superfluous. The third 
example is a direct mode loop showing some possibilities in this direction. 
The separetion of sign from magnitude is illustrated. 


Of the remaining examples, one is a function definition which I've quoted 
from someone else's program. It is intended as a rounding routine, in which 
a sum of money, either positive or negative, is converted into the same 
amount in cents/pence, but rounded to the nearest cent/penny. Again it 
shows how the value of +1 may be used; unfortunately, in the case of neg- 
ative numbers, it rounds down too far. A sign that the programmer was 
trying to be over-clever? The other example, which ia quoted under ON, 
converts ~1,0, and f into 1,2, and 3, the range required by ON ... GOSUB 
in our example, This is equivatent to the FORTRAN construction 


IF (X) 100,120,240 


and ia sometimes useful when converting engineering-styte programa for such 
purposes as pipe diameter calculations to run on microcomputers. 


Abbreviated entry: sG 
Token: $84 (190) 


Operation: Firatly, « short subroutine is called which loads the accumulater with 
Q, 1, ov SFF depending on the sign of the contents of accumulator #1. This 
Is determined firstly by the exponent: a zero exponent conventionally denates 
a@ zero result in the accumutator. If this ia non-zero, the high bit of the 
wign byte is tested; if set, the number Is negative, The accumulator ty 
joaded according to these tests, Just after SGN is a routine which converta 
Integers to floating-point volues, and this [s simply dropped into, after the 
low byte has -1/0/1 put In it, and the high byte 6. Tha exponent Is gut 
at #358 since the maximum tm 255. (Other entries from the main fixed -to - 
floating point routines load #$90 Into the exponent). 


ROM entry points: 


BASIC 1: $0B0B (54076) 
BASIC 2: $DB45 (64133) 
BASIC 4: $CDEF (62501) 


—r a eee ee 
"Anide from the Identical pronunciation, this functiosg has little ia ocmson sith 
MIs, 
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SIN 


BASIC arithmetic function 
Gians. 
PURPOSE: Evaluates the sina of the argument, which Is assumed to be in ra 
The sine is a ratlo which is constant for any angle; the diagram illustrates 
this ratlo, 


lly correct 
Syntax: SiN(arithmetic expression), The expression must be syntactical 
‘ and within the range accepted by the floating point togic (41.7 E38 approx). 


Modes: Direct and program modes are Doth valid, 
Examples: PRINT SIN(1} prints sine of 1 radian = .843 approx. 
PRINT SIN(3460 * [pTy/1a0) prints aine of 360° = 0. 

10 Q=180/[P1]: FOR J=0 TO 90; PHINT SIN(J*°Q); NEXT 

120 EeA+BIN(A)/2: Y=At+ BIN(A)*3/2; REM TROCHOID 


The first examples show SIN used In direct mode calculations. The third 
example is a loop which prints out the value of sine, aa calculated by the 
CSM, for angles from zero to ninety degrees. Example four calculates two 
coordinates which depend on a single parameter A. Innumerable formulas of 
this type exist. 
ight-angiled 
Notes: {1] The diagrams show the eine in terms of the asides of a rig 
rangle: and the concept of a radian. 'O’ and 'H' by convention represent 
the opposite side to the angie and the hypote respectively. 
H 


rT 


9 
SIN(X) = O/H Angle = T radian 
i he angie: this function 
(2) Accuracy is not greatly affected by the size of t 
operates by dividing the argument by 2*pi and taking the remainder, s0 
there is no series approximation error related to the size of the argument, 
only the error caused by the limited precision to which the argument is heid, 


{3} See the appendices for the inverse function ARCSIN. 


Abbreviated entry: sl 


Token: SBF (191) 
Operation: The argument is evaluated and stored in both floating point accuaulat- 
a ora, Gocaulaier #1 ds divided by 2*pi (6.293..}, and this result moved to 

accumulator #2, The Integer value of accumulator #1 la generated, and the 
difference between accumulator #2 and accumulator #1 stored in eee 
#t. This completes the processing of the argument. Its sign byte ls cei 
onto the stack, and on exit recovered; if negative, the sign of the result 
ig made negative. The calculation haa {lve constants and an additive con- 
stant; powers up to and including the fifth are therefore uged. 


ROM entry palnts: 


Basic 1: $DFAS (57253) 
BASIC 2: $DFDPF (57311) 
BABIC 4: $D299 (53897) 
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SORT 


System command unavalisble dlrectty in CBM BASIC 


PURPOSE; Arranges data in alphabetic, alphanumeric, or ASCII order. ASCil 
order is the most common, since it corresponds directly with the way data is 
atored, but any other sort criteria may be used. Generally, computer-sorted 
data will not always correspond exactly with data sorted by manual means, 
because some of the underlying conventions may differ: for example, Mc’ or 
Mac’ untesa specifically checked will not precede all other 'M‘s. 


Versions: Sorting (of cheques 4c) is in widespread use on large computers, often 
with merge routines, by which dally transactions update master flies. This is 
a ponderous technique which is rather rare on micros. IBM‘s 8100 machines are 
tuliy equipped with the necessary commands of this type, but this is unusual. 
Some multi-key sorts have been written for CBM hardware including a Compu /- 
think disk version, There is a sort-merge in Nick Hampshire's ‘Library of PET 
Subroutines'. The ersiest sorts to write are for I-dimensional arrays, and 
BASIC versions embodying all the common algorithms exist. (Knuth's many- 
volume work is a source of algorithms). Some machine-code hardware sorts 
are available. M Lake's bubble sort (Practical Computing, Apr. '80} ia in 
machine-code; CCN, Oct.'81, has a Shell-Metzner sort - for integers only. 


In any but the most trivial applications, sorting tends to come to grief on the 
twin prongs of space and time. [f the whole of a batch of data cannot be fitted 
into RAM, aubgets must be sorted individually, and the resulting files merged. 
The necessary disk (or tape) manipulations are likely to be slow. In practice, 
this may be tolerable, since long processing times may nevertheless compare 
favourably with the time needed to type data in. Section 4.11.4 has more on the 
subject, including descriptions of the merits of the sorts presented here, of 
which there are seven, including one in machine-code. A yraph (on the final 
page of thls section) shows the approximate range of timings to be expected. 


Notes: {1} ORDER. Numerals are especially liable to be sorted into what appear to 
be strange sequences. String comparisons In most micro BASICs compare 
successive characters until either a string comes ta an end, or one character 
differs from the other and the ‘smailer' is found. So "49" is lesa than "5", and 
"5" ig tess than 751° in CBM BASIC. The strings 0 to 25, sorted like this, 
emerge: 0,1,10,12,12,13,14,25,16,17,18,19,2, 20,2 ,22,23,24,25,3,4,5,6,7,8,9. 
if the sort deals with numbers only, they can be output in numeric order, but 
many sorts deal with atring data because of its universal applicability. 

[2] SORT FIELDS. It follows from note [1] that programming can often be 
simplified by careful choice of the way in which items to be sorted are arranged. 
For instance, a date held in the format DDMMYY may need three separate 
comparinons, of year, month, and day, But YYMMDD automatically sorts Into 
the correct order, because ycars are more significant than months, and months 
than days. Similarly, the fact that the comma hag a lower ASCII value than any 
letter ensurea that names, held with commas, sort correctly - “Williams,P.R." 
when sorted on Commodore's criteria comes before “Williamson,A.B.”. 


1, The Tournament Sort. 


10 ENPUT “SORT HOW MANY ITZMA";N: BuN-1; DIM N${(B),1(2"8) 

20 FOR J=0 TO B: INPUT N${J): NERT: REM SETS UP DEMONSTRATION DATA 
900 X=0: FOR JwO TO 8: I(J)es: NEXT: REM INDEX ARRAY SET UP WITH 0,1,4,3,... 
210 FOR JeO TO 2*N-3 STEP 2: Bufe1; REM ORDERS (NDEX ARRAY IN PAIRG 
220 L(IBATCI): IF MSCACS >to NS CEC T)) THEN 1¢CB)oLCI41): NEXT 

260 NeX-1:Cel(ap: (f C<O THEN END: REM SCAT FINISHED 

260 PRINT MAC) " ";: REM PRENT ONE SORTED ITRM OF DATA 
270 TiC pad: Rem SORT LOOP If HERE 

280 Je2*INT(C/A): CHINT(C/2) +N: TF CoB GOTO 250 

900 TF 1¢3}<O «THEN E(Cpeicset): GOTO 280 

310 IF [¢J+1)¢O THEN I¢{C)m1¢F) =: GOTO 280 

B20 TCR CE): LF NSCECIoL PP eNS(T(S}) THEN T(C)mT( Jo) 

330 GOTO 280 





| 


| 
| 
| 
| 
| 
| 


Programming the PET /CE&M ~133- 5: BASIC keywords 


28 3. The Exchange Sort and the Bubbie Sort, 


O REM PFPFRRTRRS ERR OST ET TE 

i REM ### EXCHANGE SORT F4@ 

2 OREM FEPOEEETSERDF TET EETE 

3 Rem 

4 REM ## SORTS N STRINGS OF 2L CHARACTERS LENGTH; AND PRINTS TIME TAKEN. # 
5 REM ¢# RUR O eee EXCHANGE SORT ha 
& REM #9 RON 500 ... BUBBLE SORT ## 
7 REM ## GO TO $0 ... RE-~SORT SAME DATA BY EXCRANGE SORT vt 
ae ## GO TO 550 .., RE-SORT SAME DATA BY BUBBLE SORT te 
10 INPUT "NG. OF STRINCS";N 

20 DIM AS(N) 

21 REX 


22 REM AORPEEOOER TERT EEROEREAOEE REEL EL EAE CET ESEAE ZEST OEEEREIOROREREST ERE ETEEE 
23 REM ## FILL THE ARRAYS WITH FAIRLY LONG STRINCS; INCLUDING RANDOM LETTER ## 
26 REM POREHEPORODEEODSLAROEE IRS ED ERED EREES CET EOTECETAODEEEPAEREASEAOREEEES IEE 
25 J = RND(-1} : REM NOTE: THIS SEEDS A CONSTANT RANDOM NUMBER 

30 POR f= 1 TO Ws AS(J) = CHRS(6S+RND(1) 926) + RRA RHR REE EEE EEE 

40 WEXT: REM THE SEEDED VALUE ENSURES IDENTICAL STRINGS IN THE BUBBLE SORT 

50 T = TI : REM STORE CLOCK TIME : 


$5 REM 

96 REM SOFPFETRECT AREF EAT EEE ETETEE 

97 REM #44 PERFORM EXCHANGE SORT ##Ff 

He REM Tiiistisse es 
REM 


140 FOR J = [| TO Nl 

210 FOR K + J+t TON 

220 IF AS(1) > AS(K) THEN TEMPS = AS(J): AS(J) « AS(K}: AS{K) = TEMPS 
130 NEXT KE 

140 HEXT J 

145 REX 

146 REM 

190 PRINT(TI-T}/60 "SECS" 

ci al FOR J=1 TO Nz ? AS(J);: NEXT: REM OPTIONAL PRINTOUT OF SORTED STRINCS 
305 REM SERFPEROEROSSEORT OER TENET E 

310 REM ## END OF EXCHANCE SORT ## 

315 REM PEPSERREESEAL ESTE ET RATES 

320 REX 

S00 REM #ESSSESORERAEROEEET OE 

502 REM ### RUBBLE SORT #96 

502 REM FERSOREEREEE PORTE OSE 

503 REM 

510 INPUT "MO. OF STRINCS";N 

520 DIM AS$(N} 

325 J © WND(-1} 

$30 FOR J = 1 TO NM: AS(S) = CHRS(65+ RND(1)#26 ) + "HAMRMAARAAREE LETHE" 
340 NEXT 


330 T = TL 

5395 RRM 

396 REM TL 
597 aey $##) PERFORM BUBBLE SORT #49 
aa aH OPPOERPERAEOELEIEREDAEDELOET 


600 FOR J = N~1 TO | STEP -l: FiNe=1 

410 PoR K = | To J 

620 IF AS(K) > AS(K+1) THEN FIN|Or TES = AS{K)1 AS(R) = AS(K+L): AS(K+[) = TES 

630 NexT K; IF NOT PIN THEN NEXT J 

64S RIM 

546 PRIM 

690 PRINT (TE-T)/60 “Secs” 

iia eet FOR Jal TON: 7 AG(2)52 NEXT: REM OPTIONAL PRINTOUT OF SORTED STRINGS 
’ 
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46 S. The Shell-Metzner Sort and Quicksort. 


4 EEN Be erate CELT EE es eee erent nensacntsnsae sce ceacsses (erereliitii 
5 REM $## SORTS STRINCS USING SHELL~METZNER SORT AND PRINTS TIME TAKEN 

6 REM fF RUN e+« PERFORMS SHELL-METZNER SORT " 
T REM ## GO TO 50 ..- RE=SORTS ARRAY AS() tf 
a BOGHARRAT EEG TET AE CEE PEE EEEOTEETES AIEEE EEITEETRETISR EER ORETEARESERS 
10 INPUT "KO. OF STRINGS";N 

1L DIM AS(N) 

12 3 = RND(-t} 

13 POR Ji TO N: AS(J) = CHRS(65+RND(1L)%26) + "Atanakawadsprperppys” 

14 NEXT : REM WE USE SAME STRINGS AS OTHER PROGRAMS TO TEST SORTING 

50 T = TL :REM STORE CLOCK TIME 


59000 REM 
59001 REM Bees tee oh cat GONE oe OL 
59002 REM st T OF SHELL-METZNER SORT vif 
59003 REM TITTLE 
$9004 REM 


59005 M = WN 

$9010 M = INT(M/2): IF 4 = 0 TREN 59200: REM SORT COMPLETED 
$9020 d= 1: Ken -M 

59030 [ = 4 

$9040 L = 

39050 IF aS(1)248() THEN TES*AS(I}: AS(E)*A$(L): AS{L)~TES$: Im[-M: IF £>0 THEN $9040 
$9060 J= J +t: IF J >» K GOTO 59010 

39070 COTO 59040 

59200 PRINT (TI+T) / 60 “SECS” 

39210 REM FOR J = 1 TO N: ? AG(J);: NEXT:REM OPTIONAL PRINTOUT OF SORTED STRING 
39220 END 


4 REM CHORERERRROREOTEEATEETAT EGRET ERED EEELOREET EET OCEEEEETEEEEEECOEEENET 
SREM #F SORTS STRINGS USING “QUICKSORT’ AND PRINTS TIME TAKEN t 
6 RE #4 ann ees PERFORMS QUICKSORT i 
7 REM ## CO TO 50 ... RE~SORTS ARRAY AS() tt 
8 REM PTET TTRTTT TITTLE 
9 REM 

10 INPUT "NO. OF STRINGS";N 

11 DIM A$(N) 

12 J = RAD(-1L) 

£3 POR Jal TO N: AS(S} = CHRS(ES54RND(1}*26) + “REAREHRA OEE 

14 NEXT ; REM WE USE SAME STRINGS AS OTHER PROCRAMS TO TEST SORTING 


30 REM 

3L REx CRFFOEEAEEEEAOEORRETAEET ELIE 
32 AEM ##f PERFORM “QUICKSORT’ ##¢ 
33 REM SRAFEEE ER ATPECHEAEEOCET IEEE 
34 REX 


40 DIM ST { (LOG(N)/LOG(2) + 4) ,1 )¢ REM THIS ARRAT HOLDS LEFT AND RICHT STACK 
50 T = TI :REM STORE CLOCK TIME : 

100 $ = L: ST(L,0} = L: ST{1,1) =< K 

110 L = ST(S,0): R = ST{S,1}: S=S = 2 

120 d= L; K = R: X$ @ AS( (L + B)/2 >: REM PLYOT VALUE TAKEN TO AE MIDWAT 

124 REM 

125 REM NOTZ THAT LINES (30 AND 140 ARE VARIATIONS OF EACH OTHER; ACTUAL SPEED 

126 REM OF RUNNING DEPENDS ON LENCTH OF PROGRAM AND NUMBER OF VARIABLES [N IT, 

127 REM SO SELECT THE APPROPRIATE FORMAT POR BOTH LINES 2XPERIMENTALLY. 

128 RFM MANY SIMILAR ALTERATIONS MAY HE TRIED WITH TIIE PROCHAM, 


REM 
130 EF AS${t)} < X$ THEN J = J + Li COTO 130 
(40 FOR ¥ = 1 TO in6: I? AS{K) > X$ THEN K = K ~ Lr WEXT 
150 TF J» K THEN Je J+ 1: Ke K = i sc0TO 130 
{60 tPF Sf < KR THEN TRMPS = AS(I): ASCSPRAS(KDSAS(K)*THHES: JatelsRek-1 :GOTO 130 
170 iP J < R THEN S = S + li ST(5,0) + Jr ST(S,1) = 
160 R= XK 
190 IP L < ® THEN 120 
200 IF § > & THEN 110 


246 REM 
241 REM OORRRETERAAERE CREATE TEA GT 
242 REM ef PMD OF “QUICKSORT’ fee 
243 REM Oetseeereeeeeaeaseeeeeaeens 
244 EM 


250 PRINT (TI-Ty / 60 “SECS” 
ary aca FOR J = $£ TO Wt ? AS{J);t MENTSRPM OPTIONAL PRINTOUT OF SORTED STRINGS 
KN : 
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6. ‘Scatter Sort’. 


0 REM OAATERIOST ERR TTEATEDER 
1 REM Of# “SCATTER SORT” #9# 
2 REM PEAEPERCERAECHT ERI AEF 


32 REM 

A REM PEOEPPFERFAT ARES AT EEEHES CE EESI ORIG EADRELAEAT EEE AAREAOSEATRTEORTINEE EET ER 

5S REM # VERY RAPID SORT USING A SUBSIDIARY ARRAY FOR A PRELIMINARY ROUCH SORT.# 

: REM #ASSUMES FAIRLY EVEN DISTRIBUTION OF STRINGS’ INITCALS FROM A TRROUCH Z~P 
TRIM # “RUN RUNS SCATTER SORT; “COTO 50° RE=SORTS; “COTO 230° BUBBLE SORTS.# 

PRT NTI LLL LLL LLL 

9 REM 

10 INPUT "NO. OF STRINGS"3N 

12 INPCOT "APPROX. AVERAGE LENGTR";LE 

14 LE = LE + 3: REM HOLDS LEENGTH OF STRING AND [TS POINTER 

16 J = RND(-1): REM SET SEED 

20 DIM AS(R) 

30 FOR J = 1 TG W: AS(J) = CARS(6S + RRD(L) * 26) + "#ARWARARRAL EEE EEE ET" 

40 NEXT 

50 T = TI : REM STORE CLOCK TIME 


QL REM EPEPEEIFEREP EEE EEET EAE EE AE ERET EEL ERES ERASERS TEEEL ADE EERIL ERTL EREL ETP EL ELE 
92 REM # EXAMPLE ASSUMES (ASSUMPTION CAN BE CHANCED) THAT EVERY STRING BEGINS # 
93 REM # WITH AN ALPHABETIC CHARACTER: HENCE VALUES IN LINE 100 FOR LOWER AND # 
94 REX # UPPER LIMITS. THE SIZE OF A SUBSIDIARY ARRAY IS DETERMINED IN 110-140 # 
$5 REM # AND [S LARGE ENOUGH TO ENSURE A REASONABLE ROUGH SORT: f 
FG REM MPFPSERE EHO RAEROEE ERS EAA EORRERTREIERL ARIES EAEES ARES OARELERFTL REET EAT ERT 
97 REM 

100 L » 64: U @ 91: ZeO: KeO :FisO:TES={"": PL = 0: PH = 0 

101 KEM PREVIGUS LINE SETS UP ALL VARIABLES BELOW THE ARRAY, SG I[T’LL STAY PUT 
110 B = FRE (O}/(LE * N ):REM B=NUMBER OF DUPLICATE ARRAYS WHICH COULD PIT MEM. 
120 IF B < 2 THEN PRINT "INSUFFICIENT MEMORY”: END 

130 IF B > 4 THEN B = 4 

135 PL = PREK(46) : PH = PEFK(47): REM STORE CURRENT END OF ARRAY POINTER 

140 DIM BS¢ BAN + 30 ) : REM SUBSLOLARY ARRAY: MOST OF IT WILL REMAIN NULL. 

142 BEM PAPORRASEER ESCORT AAPA EATS ADEE RAMEE TE EE ADEE ER EL EERE OD EEEOET AGEL ERE AEE 
143 REM ## CALCULATE APPROXIMATE POSITION IN B$() TO WHICH PACH ELEMENT FROM # 
144 BEM #F ASC) SHOULD PROPORTIONALLY BELONG; FILL IN SOME OF BS() WITR THESE # 
165 REM ## VALLES, SO TMAT BS() IS SPARSELY PILLED WITH ROUGHLY SORTED STRINGSS 
144 REM SEESETPARDTARTERGELREDESODTERECESEETLOPSAATEAGTERREETORREDESESEEOELATIE 


1507 =8 #x / ( U-L }: REM Z IS A SCALE PACTOR COMPUTING THE LIKELY PLACE.. 
$60 FOR J = 1 TON: K = ¢ ASC(AS{S)} - L ) * 2: REM OF THE STRING IN 8S()- 
170 [FP BS¢K) = "" THEN BS(K) = AS(J): BEXT: COTO 190 
(80 R= K+ 1; COTO 170 
182 REM 
TBD REM PPOAEREROE EA EEAEAAE TEL EET OCATLELOERE OO ELOREOEELEGETTTUITEERTODEEEREELEE 
184 REM ## PUT BS() SACK INTO AS(), IGNORING NULL STRINGS; SO THAT AS(} NOW ## 
18S REM ## CONTAINS [TS OWN ELEMENTS AGAIN, BUT ROUGHLY SORTED: - ft 
if REM PAFPRPEAT EL EEP OPEL ORL IGRI RAOEE AEE EEER OES EOASEEA ET EOE OEAAEE ATE EEES ETE 
REM 
190 3 = ft: FOR K = 1 TO BAN + 29: IF BS{K) = "" THEN NEXT: GOTO 210 
200 AS(J) = BS(K): J = J + 1: NEXT 
2tO REM 
ZLE REM FORFO PORES ERERRES EO REAE OORT EAE ERE TEER EEEOTEEOORET ERE OOAES CREED EBET 
212 REM # RESET OLD POINTERS TO END OF ARRAY = ERASING SUBSIDIARY ARRAY: ~ # 
eee ILLIA AL 
ee POKE 46,PL1 POKE 47,?H: RfM THE SUBSIDIARY ARRAY 83$() NO LONGER EXISTS. 
223 Piet SHPEEEREAT OR EADE EERE CSET ATA OH EEO OR ET AEEOEECEAREAOEES PERSE ORREEETE 
224 REM $F FINALLY, USE THE BURKLE SORT TO COMPLETE THR SORTING PROCRSS1 #8 
a rb PPPOE AIOREA ER ET EATERS OPERA ERECTED EGER EOE A CEE OOD ERTEETI ORE TORT ENTE 
eM 
230 POM J = Kl TO 1 STEP <1: FIN © 1 
232 POR Ke 1 TO 3 
234 17 AS(K) » AS(KA1) THEM PI Na: TESMAS(K}! AS(K} = AS(KEE)1 AS(R+1) © TES 
236 WexTi [PF MOT FIN THEN NEXT 


272 weM 

271 gem ITT 

274 am #80 END OF SCATTER SORT #48 

ro tea SOPRA ERT EROROORSERISOOTEIEE 
™ 


280 PENT (ti-t) / 60 “secs” 
290 REM POR J « 1 TO Wn? ASCS}PINEXT IREM OPTIONAL PRINT OF SORTED STAINGS 
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7. Machine-code Bubble Sort 
«t) 7FO2 20 70 00 85 SE AP 80 


534 8027A 20 CZ 00 B85 10 AP BO AS |) FFGR SF 20 70 00 FO A7 09 


642 $0782 11 20 £2 00 FO 07 0F 80 
450 $028A 85 11 20 C2 00 AS 76 65 88 Te en on es at AO 06 
658 $0292 12 AS 7F AS 19 AO 00 AS ~ 

‘1 7F22 SE D1 60 DO 07 CA AS 
64 $027A 1001 120007 CR AS If ‘" Fron Oe ao FO te 18 40 O2 
674 BOZA2 G1 t? FO 14 18 AO OF BL .¢ «6732 60 45 60 835 69 CB BL 


682 $0244 12 65 12 85 1B CB BL 12 (t 7E4A 65 61 85 AL AS 69 BS 


890 SOZEZ 45 42 GS. (3:A5 4882.12!) Sra cg pa AO /OS Bia Bs 
698 $OZRA 90 DB AO OS BL 128515 "' 524% ce gi 60 BS 2 DO O2 
704 s02C2 CB B1 127 8S 14 DO O2 Cb 2 
Aid? SO2CA- 15<CES14 AA ANTA2 A OT, 8 “LE S2 ES CB Se 1B AS E007, 

1 TESA 85 SO AS 61 69 00 B85 


722 80712 AS 12 AS £3 69 00 85 13 
730 $020A AS 14.D0 0266.15 co 14 (1 EB? AS 62 DO 02 ee eos 
738 $07E2 DO O4 AS 15 FO 1285 18 ': F599 ao oo ae a4 Ab ES AS 
746 9O2EA AZ 00 86 16 86 17 AS 12. | Se7a as a7 AS 61 85 BS FO 
734 «802F2 85 19 AS 19 8S 1A FORO '! 5509 Fo Oo oS os a? 69 09 
7e2  $02FA FO 72 18 AS 196903 8S ‘! Gran 47 AS B49 00 BS 4B 
770 $1302, «19 AS 18. 69 00 BS 1A ES |) 5568 24 ho oO Fe BS AO OF 
77@ $030A 16 00 O2 Ea 17 AO O2 BL‘! bF0n by oy BA 60 88 10 FB 
786 $0312 19 97 BO 00 8B 10 FA AO 


ad a 7 
794 $091A 05 Bi 19 99 B7 00 8B8CO ‘! Jean oF BOTS BA SB ES cA 
602 #0322 O2 DO Fé AA 38 ES BO 90 5 
»t 7FB2 02 AS 64 AO FF E88 CB 
810 $032A 02 Ad BO AO FF FB C8 CA 
3 +1 7FBA BO OB AS 6D CS 6A 90 
e18 s03%2 DO 08 AS BA C3 BO 90 CA 
«i ?7Fl2 BO 22 B1 4E D1 6B FO 
a26 $033A BO 22 B1 BB Di &1 FO EE 7 > 
++ 7FCA 10 1A AD O2 BY SD 00 
834 $6342 BO 14 AO O02 BF BA OO FE 
+ 7FD2 67 88 10 F& AO OS BY 
a42 $0344 19 88 10 FB AO OS BF AD ; 
>: 7FDA 00 91 67 88 CO O02 DG 
850 $0352 OO 91 19 8&6 CO 02 DO Fé 
2 =f 110 7FE2 A9 00 83 64 AS 62 CS 
asa $0354 aA? 00 85 18 AS 14 CS 16 
846 $0362 DO 98 AS 15 C5 17 DO 92 oS Aa BENS Aone ie, oa Ao. oe 
+t 7FF2 43 64 FO 8A 60 


874 $0364 AS 18 FO 84 60 
BASIC 3 (‘OLD ROM’) 


Both these routines are Freely relocatable; the old ROM version has been put into 
cassette buffer #1; the BASIC 2 or 4 version is positioned in the top of 32K memory, 
where POKE 53,127:CLR will protect it from BASIC. The syntax needed to run the 
sort Is shown by this demonstration program :- 

0 INPUT "NUMBER OF STRINGS";N: DIM AS(N): REM ARRAY AS{) £3 SET UP 

a FOR Jal TO N: ASCJ}<STRSCINTCRND(L}*LOOO0O): NEXT: REM PILL ARRAY 

4 SYS 32514:A: AEM THIS SORTS ARRAY A${). BASIC 1 VERSION I5 SYS 634, 

@ FOR JeO TON: PAINT "STRING NUMBER" J" 13 " A$(J>: NEXT 
These routines operate in program mode only. The string array must exist and be 
l-dimensional, The sorted order ia the snme us BASIC; for example, null atrings 
come first, The strings need not be sorted from their initlal character: o sort key 
can ba defined starting within a atring, See elsewhere for details. Finally, note the 
syntax ip SYS 634:A to sort AS(), and SYS 494:PQ to sort PQ$<}, and so on. 


10000 


1600 









Shell-Ketzoer 
Quicksort 
"Soatier' 


100 






Bubble (machias-code) 





io 
Bubble re-sort (m/cods) 
See ae 
19 B40 780 __To60 


| nT 
a-- NUMBER OF STRINGS TO BE SORTED --- 
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8$ 
80 
a5 
AS 
SF 
B1 

60 
40 
63 
Ccé 
OF 
oi 

62 
66 
60 
EO 
83 
Eé 

BL 
AQ 

co 
90 

CA 
OA 

EE 
Fi 

&? 
Fé 

64 
92 


a 


| 
; 
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SPCC 


BASIC forma! function 


PURPOSE: Prints a number of spaces or cursor-right characters on the screen 
or to a printer. The number depends on the parameter in brackets. This 
instruction is normally only used within a PRINT statement, 


Syntax: PRINT ... SPC(arithmetic function}. The arithmetic function must take, 
after rounding down, a value in the range 0-255. No spaces may appear 
between SPC and (, except in BASIC 1. The interpreter will treat such a 
construction as the array SP(). 


Modes: Direct and program modes are both valid. 


20 PRINT "[CLR]": FOR J=O0TO20: PRINT “[SHIFT-&j" SPC(38) “(SHIFT-&}": 
NEXT . 
30 FOR J=0 TO 19; PRINT SPC(J) "*" SPC(38-J*2) "*": NEXT 


These examples show how SPC may be used within a loop to print certain 
repetitive types of design on the screen. The first provides a border down 
each side of the screen; the second a V-shaped pattern, 


765 PRINT SPC(10)"The PET can run while the disk is processlog” 


This program line lustrates the typical use of SPC in the straightforward 
printing of literals. Since SPC( when tokenised oecupies 1 byte, line 765 
is six bytes shorter than PRINT “ The ...%. This may or may 
not be a worthwhile saving. And the appearance on listing may or may 
not be improved by the function. 


Notes: {1) SPC( and TAB( share a peculiarity concerned with printers. The 
point is that SPC( and TAB( are processed in virtually identical ways by 
PRINT, sharing the bulk of the same routine. In addition, the earliest 
BASIC, presumably with screen PRINTing in mind, uses PET's cursor right 
characters to generate ‘spaces' in each of the commands. These characters 
are not of course universal; BASIC 2 and 4 were modified so that spaces 
(#$20 characters} are sometimes produced by SPC( and TAB{, In this way 
other printers could be used with these functions without printing spurious 
information. The following short program illustrates the difference, and 
the location to poke if either command is giving trouble.* Its effect is clear 
when the program js run: in one case (when the device ls 0, i.e keyboard) 
SFC( does not print ‘spaces’, but skips right, leaving the previous screen 
contenta as far as possible unchanged. But the poke, which is interpreted 
as a change of device, causes exactly the same inetriction to print spaces. 


Examples: 


10 INPUT X 

20 BOKE 14,X 

36 PRINT "(HOME)“:: FOR J=Q TO 30: PRINT "X"s1 NEXT 
40 PRINT "[HCME]**" Tag( 10) "*** SPC( 1d) "**" 
READY. 


9 © RXKMAKKA # OAXAAARAAN * *KAAXRKAKA 
ae ” * YXKKANR 


Top line when £90) bottom line whan X=1, 


Abbreviated antry; «#? (includes left parenthesis} 
Token: $AG (166) 


Operation: See PRINT. Ef SPC( la found In a print atatement, tho expression in 
parenthesos Is evaluated and yvatidated as usual, (The rlyht hand bracket 
has jin own chock). The resulting alngle byte is told in the X register 
and counts the characters as they are singly output, 


ROM entry points: BASIC]. $CAIB (61728) BASICZ:$CAGD (51725) BARICS: Bh0F (47H) 
*The puke is helpful in ather eaye: @.g, shen printing w tootkit DUMP or FIND. 
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BASIC arithmetic function 
PURPOSE: Calculates square roots. 


Syntax: SQR{arithmetic expression). The expression must be valid end evaluate 
to a rlon-negative quantity which is within the range accepted by the floating 
point logic. A negative argument yiclds an ?7ILLEGAL QUANTITY ERROR. 


Modes: Direct and program modes are both valid. 


Examples: PRINT SQR(Z) :REM £.4142,., 
PRINT SQR(9) :REM J 


1000 KL = (-B + SQR(B*H - 4*A*C)) / (2*A) 
1010 X2 = (-B - SQR(B*B - 4*A*C}) / (24A) 


1240 D = SQR(X*X + ¥*¥ + 2*Z) 


SQR, like EXP, is not really needed in BASIC; either function can be 
obtained using the ordinary power (upward arrow) evaluation, The first 
examples can be replaced by 21.5 and 9#5, for instance. It is generally 
included because square roots occur more often than most other powers, and 
because in any case it lonks better to have more functions. SQR is faster 
than raising a number to the point five, and is also more readable, and is 
perhapa justifiable on the latter ground alone. At any rate, the two first 
direct mode examples print the results of typical calculstor-style square root 
evaluations. Only the positive root is printed: the two-line program embody~ 
ing the solution to the ‘general’ quadratic equation has a repeat line in which 
the negative root is processed. The final example is another formula having 
@ square root within It; this is an extension of Pythagoras’ theorem to find 
the diagonal within three planes at right angles (i.e. a room or box etc.) 


Notes: [1] A square root, as those people who have forgotten may like to be 
reminded, when multiplied by itself gives the original number, of which it 
is the square root. Thus, 3 is the square root of 9, because 1*3=9; and 
(more debatably...) 1.4142135,.. is the square root of 2. Early computers 
worked this out by iteration: the relation 

Koa” sas provided continually better estimates for SQR{Y). 
ax 
‘2 


(2] Other powers can be set up in machine code by Imitating the SQR mode 
of operation. In BASIC 4, this routine, called by USR, will return fourth 
roots instead of square roats: 


JER $CD42 (Decinal aquivalenta: 

* 
peed teas 42,60, 208, 189,8,180, 211,78, 16,209) 
wu $D10F 


A and Y point to an address in ROM holding .25; more generally, the value 
won't exiat in ROM and will have to be put into RAM. 


(3] In lower-case mode, shift-colon prints e square root symbol, (Ora tick?) 


Abbreviated entry: aQ 
Token: $BA (188) 


Operation: SQR ia positioned Immediately Lefora tha power routine which computes 
x¥, It moves the argument up Into floating point accumulator #2, then loads 
accumulator #1 with the flonting polnt form of .5. Then It deopa inte the 
power function, ao that x¥ is ovaluatad ag the special cane x-", 


ROM entry points: 


BASIC 1; 3DEI¢ (86949) 
BASIC 2: YDESE (66026) 
BASIC 4: OD10e8 (83612) 





\ 
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ST 


BASIC reserved variable 


PURPOSE: provides a record of the status of the system after any read or write 
operation to tape, printer, disk, or other peripheral. In this way, an error 
condition can be noted without stopping BASIC. The variable ST is reset to 
zero at the start of each input/ output process, 


Syntax: ST resembles a real variable, and may be assigned, printed, and used in 
tests with a conditionai statement. ST is not stored in the RAM area which 
holds other variables; it is generated when needed from a single byte. For 
this reason ST is not a keyword and is not tokenised, BEST therefore is a 
legitimate variable name, equivatent to BE. STATUS is equivalent to ST. 


Modes: Direct and program modes are both valid. 


Examptes: The table shows the possible meanings of ST, with notes on interpreting 
them, In each case ST takes the value of a power of 2 (1, 2,4, 8, etc.) when 
it is non-zero; each erromtype ORs the byte holding ST with #1. #2, or which- 
ever is the conventional value. Note that cassette processing, which does not 
use the IEEE bus, has a different set of meanings from those returned by all 
devices 4 and upward, i.e. printer, disk units, modem. 


ST sT Cassette #l or #2 | IEEE (e.g. ali CBM peripherals) 
(hex) (dec Read 
1 


End of file (EOI }** 
Device not present *** 


End of file on input** 
End of tape marker *** 





rite 
Input time out * 
4 Short block on input?! 
Long block on input? 
Mismatch on checking? 1 
Checksum error? 


Means that after PRINT#4, "MESSAGE" ST takes the value of 1, implying that 
the device responded in a longer time than 65 milliseconds, or may not have 
fesponded at all. Some CBM printers return 1 even when working perfectly. 
This is more important with modems than printers. where it is usually obvious 
if the device isn't printing correctly. Error ST=2 means the device is slow, 
and has responded too slowly or not at all. Typically, a statement like this: 
100 INPUT #5,M$%: IF ST=2 GOTO 100 uses ST with a alow peripheral, Note that 
in BASIC 4, the time out feature may be disabled: see Chapter 15's RAM map. 
‘Tape data files are read into the cassette buffer. One block occupies 192 
bytes, If a program file is read instead, one of these errors will occur, since 
the anticipated separation Into biocks won't be present. 

IEKither or both of these errors may occur on reading tape, with INPUT# or 
GET#, or LOAD, or VERIFY. They are part of the tape security system. 

On LOAD, for example, if the Inconsistencies between the two programs which 
are recorded on tape are too great, ST is wet to 16 and 7LOAD ERROR stops 
BASIC. (A checksum error doesn't generate thla message, because ST ifs 
ANDed with #$10, which is why tape loads can be faulty but nevertheless seem 
to be OK). Note that VERIFY can be run in program mode, |.e. from within 
@ program, so self-checking of a program ioad is possible, though time-con- 
suming, with tape. 

49a fle, if it has bean CLOSEd correctly after belng written, haa a marker 
to indicate end-of-flln, So BASIC like this: 166 INPUT#2,X$: IF ST=64 GOTO 
1000 provider a typleal moana of checking for end-of-flie. Since fllen may 
be of any tength, some auch method ta necessary, of course, but often it la 
eanier to write ong's own marker, or keep a record of the number on file at 
the start of a file, 

***A4n ond-ot-tape marker ls almply a block on tape holding a apeciai number, 
The tape need not, in fact, and there; Its Function is purely to atop the tape 
Fecorcer from attempting to read blank tnpe or tape holding unwanted data. 
Thie wil couse ASIC to crash with a ?FILE NOT FOUND ERROR, The 
Corresponding IEEE status means device doesn't reapond; If the onilre [EEE 
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bus is unresponsive, again BASIC will crash, In this case with DEVICE NOT 
PRESENT ERROR. But if the bus Is partly active, ST is set to -128 without 
a program crash, so that a program loaded from disk can use thia test to 
determine whether a printer is turned on and, in the event that ST returns 
set to -129, print a warning message to the screer. 

OPEN 5,5: PRINT#S: PRINT ST : REM GIVES ST*-128 IF DEVICE 3 DOESN'T EXIST 


Notes: (1] ST is act to zero by GET, INPUT, and PRINT in addition to the input/ 
output commands CMD, GET#, INPUT4, and PRINT#. The information within 
ST therefore must be tested after every input or output, if you are using 
ST. This ephemecrality does not apply to the disk stutus variables DS and 
DS$. When both are in use, test ST first, with, for example: 
IF ST OR DS THEN: REM ERROR OR END OF FILZ PROCESSING ROUTINE. 


(2) Limitations of ST. This variable illustrates one of the dilemmas which face 
anyone attempting to design a good computer system. If the hardware is 
reliable, but not infallible, how can errors be signalled to the computer? The 
program may simply stop. or alternatively some indicator can be used, but this 
may be ignored, Either way has its drawbacks. The status byte, used from 
BASIC, combines a bit of each, Some errors, those which are more difficult to 
detect, are not implemented, For example, there is no facility to read back tape 
immediately after writing to it, so tape write errors are undetectable, except 
for programe which may be VERIFYed. Many of ST's messages can be prog- 
rammed around, notably the end-of-file status. It is, in fact, entirely feasible 
to ignore ST altogether. 


(3) BASIC>1 holds ST in location $96 (130 decimal). BASIC 1 uses $020C 
($24), When reading files in machine code it is common practice to check 

for end-of-file by reading ST, which ia a simple operation. Chapter 14 has 
details with examples. This method is not always usable, because some 
devices don't set EOI true on the last byte of data, but send carriage return 
and line feed instead. 


(4] Like Tf, ST can be set up ag an ordinary numeric variable. If a variable 
is assigned a value from BASIC, found with VARPTR, and altered to ST, you 
will have an assignable ST which can be given values like 999 at will ~ to the 
considerable surprise of some other programmers. 


Abbreviated entry, Token: Neither of these are applicabte. 


Operation: A special ROM routine performs an inclusive OR with the location which 
holds ST whenever an error ig found. The accumulator is loaded with #80 or 
whatever and the routine called to enter it. For this reason it may be possible 
that several errora simultaneously are included in ST. Apart from this side 
of things, several routines exist in BASIC to watch for ST and process it 
if found; PRINT has a subroutine to evaluate variables In which ST Is checked 
and this is used by assignments too ('X=ST' say}. The routine to create a 
new variable tests for all the reserved words, rejecting attempts to set ST. 


ROM entry points: 


Fieg in error: Look for 8T, process it: 


BASIC 1: SFBEG BASIC 1: $CESR 
BASIC 2: $FHv7Fr BASIC 2: SCETS 
BASIC 4: $FBC4 BASIC 4: COOF 
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STOP 


BASIC command 


PURPOSE: Causes a program to exit to Immediate mode and print a message 
Indicating the line at which STOP was encountered. Like END, this command 
may be used to set breakpoints In BASIC programs. CONT causes 4 pro- 
gram to continue at the next instruction after STOP. 


Syntax: STOP has no parameters. It may de followed by spaces, and must be 
followed by an end of statement byte - either a colon or a zero byte at 
the end of the tine. 


Modes: Direct and program modes are both valld, Direct mode is of little use. 


Examples: STOP Is not often used in finished programs, since users of a program 
are unlikely to want information about esoteric matters tike the internal 
workings of BASIC. [ts importance lies in this fact: since the line on which 
it was found is printed, breakpoints can de scattered throughout programs, 
and particularly in difficuit parts of a program with bugs. 


1901 IF X<> VAL(X$) THEN PRINT“ROUNDING ERROR": STOP 
$10 J$e"€$ek “: FORJ=H1TO LEN(J$); IF IN$<>oMIDS(J$,J,1) THEN NEXT: 
PRINT "**VALIDATION WRONG" : STOP 


Both these examples illustrate the use of STOP as a temporary measure, 
put in to trap errors which may occur through faults in other parts of a 
Program or subroutine. In the first case, X$ is supposed to have value 
equal to X; in the second, only characters in the string J$ are supposed 
to be present as [N$. 


Notes; [1] When a program exits te direct mode, any variable can be printed and 
changed without effect on the program. CONT will still operate. [f entirely 
new variables are Input. CONT usually still operates. 


[2] Editing a program will cause CONT to reply with 7CAN'T CONTINUE 
ERROR. Some BASICs (eg Sharp) permit a shortened, edited program to 
retain ita variables, and machine code routines to do this can be written 
for Commodore BASIC. Usually though editing loses the variables, 30 the 
Program must be run again to reach the same position as obtained before. 


Abbreviated entry: sT 
Token: $90 (144) 


Operation: This routine is virtually identical to END, except that on entry, the 
varry bit is set, so that the finat branch near the end of the routine prints 
"BREAK IN” followed by the linenumber. 


Note that FFE1, the ROM routine to test the stop key, calls this routine; if 
the stop key was pressed, this sete the zero bit and STOP [s entered as 
though the command STOP had been encountered. 


Rom entry points: 


BASIC 4: $CTIC (S0972) 
BASTC 2: &C73F (51007) 
BASIC 4: $B7C6 (47046) 
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STR$ 


BASIC string function 

PURPOSE: Converts a number, or numeric expression, into a string. When held 
In string form a number cannot be added to or multiplied, but is instead a 
string literal, which can be edited, formatted, and modified like other 
strings. 

Syntax: STRS§(arithmetic expresaion). The arithmetic expreesion can take any 
value accepted by the floating-point accumulatora (up to about #1.7 E 48). 
However, not all the accuracy of the original is necessarily retained. This 
function uses the same buffer as PRINT, and its results are held in exactly 
the same way. Thue, STR%(.005) is not "005" but as " 5é-03". 

There must be no space between STR and # unless you wish array ST$() 
to be understood. (BASIC 1, however, allows this space}. 


Modes: Direct and program modes are both valid. 

Examples: PRINT STR$(123) + ”.00" : REM AZSULT 18 123.00 
1210 N$aMID$(STAS(N) , 2) : REMOVES LEADING SPACE FROM +VE N 
PRINT “$" + STR$(DOLLARS) + " =TOTAL." 


The major uses of this function are probably routines to round and edit 
numerals, and routines to compressa numerals for storage when disk space 
is limited. Both these techniques are too elaborate to discuss here: see 
PRINT USING and Chapter 4 respectively for programa. 


The first of the three examples above is a small scale editing program. 
PRINT 123 simply printa 123, and so does PRINT 123.00, Trailing zeros 
cami be introduced in BASIC only by use of STRS. The second example 
is another editing routine; the leading space which CBM BASICs introduce 
in positive numbers (this space holds the minus sign with negatives) can 
be unwanted. Suppose you wish to edit numbers less than | to appear as 
0.05, 0.36, etc. "O"*STRS(N) for small N gives 0 .05 which of course is 
the wrong format. Line 1210 removes the space, and will also remove 6 
minus sign if there is one; I'm assuming all the quantities are positive. 
(incidentally, not all BASICs do this. Apple BASIC hasn't the space), 
The final example shows that STRS is a genuine string function, and can 
be concatenated and proceased like other strings and literals. 


Notes: (1] Summary. For numbers in the everyday range, this function iz fine. 
The most likely bug is caused by the conversion routine mentioned already. 


STRS$( 1294000000000) ts not 1234006000000" but "1.234E12". Many rounding 
routines fall into thla trap at the low end of the scale. A number supposed 
te be zero may accumulate rounding errors and appear as i£-9, 
The leading space feature can be demonatrated like this: 

PRINT “*’STR9(24)"*" prints * 24%, while 

PRINT "*"STR$(-24)""" prints *-24*%. 


Abbreviated entry: etR {includen $) 


Token: $C4 (106) 

Operation: This function is a good example of u string assignment and would be 
helpful if a string USR function or string function definition existed with 
BASIC. First of all, the numeric mode flag Is checked; tf Iacation 7 (in 
BASIC>1) hae its high bit not act, Indicating that the expression WAR 
numoric, thls la accepted. So STR&C"ONE") ix reiected. Now the KOM 
routine, shared with PAINT, Is called which pula the ASCIE equivalent of 
the number Into SOOFF - $DI0F. A subroutine return oddress is popped 
from the stack, pointers are set to $OOFF, and the string set-up routine 
Processes the string exprension of which BTRS Is a part, perhaps giving @ 
? FORMULA TOO COMPLEX ERMOR, bul probably, we hope, uot. 


ROM entry polnts: 


BASIC 1: $D349 (54068) 


BASIC a: $D33F (64079) 
Basic 4; SOON (50874) 





ere ee pie A: 
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SYS 


BASIC system command 


PURPOSE: Transfers contro to the address following SYS. This ts executed as 
§502 machine code until! an RTS. instruction or equivalent is encountered 
which corresponds to the SYS command; at this point control is resumed 
by BASIC, This command is essential in running machine code subroutines 
and is often used to run large machine code programs. Some knowledge of 
$502 programming is necessary to understand this command, 


5: BASIC keywards 


Syntax: SYS arithmetic expression. The expression must evaluate to a numeral 
within the range 065535; non-integers are rounded down. This is a 
command, not a function: X=SYS 634 is invalid. Brackets are not needed. 


Modes: Direct and program modes are both valid. 


Examples: SYS 114096: REM THE EFFECT IS IDENTICAL TO 9YS 45056 (OR SYS 48054.4) 
1230 S¥S CH: REM CH AAS AEEN ASSIGNED 926 
12300 SCAROLL*57377; SYS SC: REM SCROLL UP WITH 8032 


These three lines of code show typical SYS calls: the first enters a routine 
at $B000, perhaps a Toolkit. The second and third show algebraic addresses 
where the sys cali may be varied; the effect of the first depends on the 
code contained at address CH; the second is an actual entry point for the 
8632, SY5 of a ROM routine is of course always reliable - provided that 
the address ls right and the ROM set hasn't been changed - whereas RAM 
routines must always be loaded or poked into memory. Readers not yet 
familiar with machine code might try the following short demonstration: 
POKE the vatues 162,0,134,157.0, 128,232, 208, 249,96 into $00 to 909. These 
numbers correspond to this machine code: : 
SYS 900 disptays all 256 VDU 900 $0384 LDX #$00; Load X with zero 
characters on the screen. The 002) $0386 "TIA i Teaneter * tO 
routine can also be called at 903 $0387 STA $8000,E; Put A into VDU 
other entry-points: SYS 902 906 $038A [NX go dRerenent.k 
for Instance has results depending 907 “S0I0B. BNE ($0986). -j Branch if °Xs>0 
on the entry vaiue of X. 909 $0380 RTS ; Return 

routine can Itself be modified from BASIC; this d - 
the routine 256 times, modifying the screen address cash ines asi 


FOR Ja) TO 256: PORE 904,J; SYS G00: NEXT 


Examples in ROM: BASICs 1 and 2 extend from $C000 to S$FFFF; BASIC 4, with 
added disk instructions, is longer and occupies $B000-$FFFF. Each BASIC 
has ROM misaing from $£300-SEFFF; so early BASICs occupy about 14000 
locations, while BASIC 4 takes up £8000. There is about an evens chance 
of a location taken at random wilt directly enter ROM as BASIC runs it; 
there {s a high chance that SYS of such a Jocntion will either go into some 
variety of loop, or change some of the tocations and variables used by 
aa Machine code may become corrupted. Because of these uncertainties 
t may be advisable to resct the machine {f a SYS has been wrongly run. 
This can happen inadvertently: SYSS826 if entered by ‘return’ will be 
Interpreted as SYS S8. This Ie likely to be znro, and if ao SYS 0, having 
the same effect as USR(0), will be performed; but S@ could take any value, 


Two short demonstration programs follow, !lustratl 

: ¢ ; 1 ng strange effects whlch 
may occur with Indiacriminate S¥Sing. The cure generatly ‘A to switch off, 
ae eee betler from the hardware point of view, call the routina to set 


(4) POKE 434,248: POKE 635,96: 8Y8 634 


al short routine acts a flag in the 6502 known as the decimal bit, GD. Now 
reiees tries to do its calculations in packed decimal mode. The attempt is 
ie auccesa, Exit to the monitor will clear the decimal bit, if you can get 
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[14] 80 REM ¢** JOKE WHICH LEAVES MEMORY IN A STRANGE STATE *** 
200 POKE $2,255: POKE 53,385; POKE 40,0; POKE 41,0 
110 PRINT "[CLEAR]" 
120 SYS 57757 : REM BASIC 2; BASIC 4 IS SYS $4321. 
(BASIC L VERSION: POKE 134,255:PORE 135, 255:POKE 122,60: POKE 123,0: 
PRINT "(CLEAR)": S¥S 57690) 


Examples. A small selection: 


BAgic 1 BASIC 2 BASIC 4 
RESET BASIC AS iF SWITCHON: $FD30 (64824) $FCD1 (64721) $FDI6 (64790) 
PRINT "? OUT OF MEMORY ERROR”: $C357 ($0007) $C355 (50005) $B3CD (46029) 


PERFORM NEW (1.2, ERASE BASIC): $C553 (50515) $CSSD (50525) 3B5D4 (16548) 
ENTER MONITOR BY 'CALL' ENTRY: not applicable $FDIL (64785) $0472 (54986) 
SCROLL SCREEN: $E559 (58713) SES3P (58687) $E3ES (59344) 
¥ SECOND D&LAY LOOP: $ESC8 (58824) $ESAS (58792) $E412 (58386) 


SCROLL SCREEN DOWN: not applicable $E32C8 (56312) 
TINALE THE BELL: net applicable $EGA4 (539044) 
SWITCH TO LOWER/ TQ UPPER CASE: net applicable $EOTA (57466) 


9£082 (57474) 


Notes: {1} Although usual, it is not necessary to end machine code with an RTS. 
An RTi can be used, provided an extra byte hes been pushed onto the 
stack to be treated as a processor status register. It is common for 
IMP SABCD to replace JSH SABCD/ RTS. Commodore's BASIC is full of 
jumps where the return is stored on the stack; the point is that the RTS 
of the called routine is used, saving one address on the stack. 


{2] it is often easier to use SYS rather than a wedge when writing routines 
to be used by BASIC. The wedge will probably need to coexist with other 
wedges, and a lot of checking for symbots like ! or @ may be required. 
SYS is also easier to handle from the point of view of returning control to 
BASIC. The drawback is that a large number of SYS addresses may be an 
irritant. 


[3] Some BASICS use 'CALL' for this commond, for instance Apple, which 
aiso uses (rether clumsy) signed integers. 


(4} The fact that SYS computes its destinatlons can be used to access 
jump tables; SYS 926 + 3*A for example with $033A JMP SABCO/ IMP $1234... 


[5} Some SYS commands (e.g. of VIC) allow A,X,¥. and perhaps SR to he 
set from BASIC, and this ia often convenient, This type of SYS begins with 
something like this: LDA SR-STORE/ PHA/ LDA A-STORE/ LDX X-§TORE/ LbY Y-8TORE 
/ PLP before jumping to the SYS address specified from BASIC. 


Abbreviated entry: s¥ Token: $9E (158) 


Operation: The expression is input, valldated, and converted into a 2-byte 
integer which is stored in ($11) in BASIC>1 In the normal 6502 way. with 
the low byte first. An Indirect Jump ls made to this address, and since 
{t holds the addrees after SYS, the correct machine cole Is executed. (An 
indirect jump is represented JMP ($0011); the destinatlon address Is landed 
from ($11}). 


NB: the argument ja converted Into two bytes, of which the high byte is 
huld in the accumulator and the low byte in the ¥ reginter, in sdditlon to 
the speciul zero-page tocations. For example, SYS (024 shown A=4 and ¥-0 
on entering tha moniter, SYS therefere dora not behave in the same way asa 
BASIC when entering KOM routines; the address in the table above for 
NEW in not quite the same as that given under NEW ltacif, because the 
validation process of KASIC doesn’t apply to 8YS. 


ROM antry points: 


Atl A0Ma use the Kernel jump tahle entry of SFPDE, trom which is called: 
BASIC 1: $Fa696 (43125) 
BABIC 2: $684 (63108) 
BASIC 4; $FEC3 (O317L) 
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TABC 


BASIC format function 


4: BASIC keywords 


PURPOSE: Prints spaces or cursor-rights to the screen, if the TAB Parameter in 
brackets exceeds the current cursor position. This instruction is normally 


only used within a PRINT statement. The f i i 
printer: e function is not usable with a 


Syntax: PRINT ».. TAB(arithmetic expression). The expression must take, after’ 
rounding down if necessary, a value in the range 0-255. No spaces may 
appear detween TAB and {(, except in BASIC 1, The interpreter will treat 
such 6 construction as TA({x), an element of an array TA(). 


Modes: Direct and program modes are doth valid. 


Examples: 3020 IF OP$(P)="" THEN L=P: PRINT TAB(15);: GOSUB 200: 
PRINT TABR(25) "7727": NB=1: GOTO 3065 


20 PRINT “(HOME)’TAB(220) "({R¥S][40 or 8D SPACES)” 

30 FOR X=40 TO 70: REM OR BD TO 189 WITH 80 COLIMNS 

40 PRUNT "[HOWE]" TAB(X) “"[ERVYS] " TAB(X+40} "[RVS}  TAB(X+120) 
“[RYS] * TAB(X+160) “[R¥S} " 

50 PRINT "“"[HOME}" TAB(X-1) " " TAB(X4+99) " " TABCX+119 " " 
TAB(X+159) " *: NEXT 


The first example is a typical print-to-screen stateme i 

disassemdler in BASIC which prints '??7' if an ilps Raye k ; 
been found, The effect is similar to that achieved by SPC{, except that 
TAB( enables easier left-justification. The second example is a small program 
in which the argument of TAB( runs across three lines. It draws a bac 
across the screen and walks a cross-piecce along it (rather slowly). 


Notes: (1] TAB( can be made to print spaces - not just cursor rights - to the 
screen, erasing the matter over which it prints. See note L of SPC( for 
information and for a demonstration program including both functions. 


{2} TAB( works by subtracting the current cursor position from 

Parameter, and, if the result is positive, dropping nto the SPC( paaes 
print that number of characters. Consequently, it will not work properly 
with a printer, unless the duplicate information is printed onto the sereen 
The same considerations apply to the TAS key as implemented on the 8032. 
Por these reasons, there is a lot to be said for avoiding TAB( and SPC( . 
unless you are certain to be using screen output only for the PRINT state- 
ments involved. And when modifying programs for other machines to run 
on a PET some conversion routine may be needed; typicaily, 


SP$x" “: REM OPACES 
PRINT LEFT$(8P3, 10-LEN(E$)} ; EY 


might be used to right-fustify, in this example apanning 10 columns. 
Abbreviated entry: ta (Includes left parentheals) 
Token: $43 (163) 


Speration: See PRINT. IF TAB( is found In a PRINT statement, the expreasion 

N parentheses Im evaluated and validated aa usual, (The right hand bracket 
han ita own check). The procenaor atatua Mags are pushed onto thr stack; 
Carry bit set distinguishes TAR from SPC( within the rautine.« Now the , 
current cursor ponition (#8 In HEAH/VTAB) Is subtracted from the eval- 
ated parameter, and, If the result ia non-negntlve, characters, elther apace 
or curror right, sre printed salngly by the SPC( routine. : 


ROM entry points: 


BASIC 1: $CAI3 (81731) ¢pr. 
OCedmad 
BASIC 9; $CAN? (81719) med slightly differentiy. 


BASIC 4; $oD08 (47880) TAR KEY: GE2ZAQ (68016) 
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TAN 


BASIC arithmetic function 

PURPOSE: Evaluates the tangent of the argument, which Is assumed to be in 
radians. The tangent is a ratio which Is constant for an angle; the diagram 
ilbustrates this. Note that this function has nothing to do with the tangent 


to a circle. 


Syntax: TAN (arithmetic expression), The expression must be syntactically correct 
and within the range acceptable to the floating-point logtc (f1.7E 38 approx.) 


Modes: Direct and program modes are both vatid. 

Examples: PRINT TAN({PI]/2) printa tan of 90°; POVERFLOW ERROR 
PRINT TAM(45 / 57.29578) tangent of 45° = 1 
100 X= (TAN(A) + TAN(B)) / (1 = TAN(A) * TAN(B)) 
S00 Am ATN( TAN(A) ) : REM CONVERTS TO RANGE =90% to +90° 


w the use of radians and of degrees; a radian 


The first two examples sho 
is 57,29578%. 30 this value may be used to interconvert between the two 


measures, 90° (pi/2 radians) and all the cyclically repeating equivalents 
Uke 270° and -90° yield an overflow error; if such values are not tested 
for, the program, although otherwise perfectly correct, will crash if such 
a value is generated in the course of processing - 


The third example is one of the very many functional relationships which 
hold between trigonometrical ratios; in thia case, the value of A is made 
equal to TAN(A*B) by the use of the standard formula. 


Fourthly, program line 500 demonstrates the connection between the arctan 
function and the tangent. A function can only return a single value. For 
this reason ATN(A) returns only the principal value of angie A, not an 
infinlte sequence of alternative sotutions. So line 500 converts angies out of 
the normal range into their principal value equivalents. 

des of the right-angled triangle from which 
how a radian is related to a circte. ‘O'and 
idea opposite and adjacent, reapectively, 


Notes: {1] The diagrams show a) the si 
the tangent Is computed, and (ii) 
ta’ conventionally represent the s 


to the angie. \ 
0 1 
TAN(x)=0/A 


(2) Another measure of angles sometimes used is the grad, where 100 grade 
make up a right angle. Pi radians therefore = 200 grads, and the conversion 


figure la 63.6620. 
(3] This functlon [a evaluated by cal 


dividing by the cosine, Its specd and 
as these other functiona. 


Abbreviated entry: None 


Token: $C0 (192) 
Operation: The argument fe evaluated and checked, then goes through these 
stages: 
The argument in stored in the tem 


Sine ja avaluated / 
The rosult ta stored in the temporary ntoruge aren starting $4L (BASIC Zi)? 


The argument In retrieved from temporary sture/ 


Cowine {a evatuated/ 

A pointer in ant to the area holding sina; and the division routine entered. 
ROM entry points: 

HABIC 1: $DFEE (57326) 

BASIC 2; $EO28 (O7384) 

BASIC 4: $0202 (B2970) 


culating the sine of the angle, and 
accuracy therefore are not s0 good 


porary storage area starting $54 (BASIC?) 





ome 


2 espera nec sien os 


1 
‘ 
QL 
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TI & Ti$ 


BASIC reserved variables 


5: BASIC keywords 


seh ara Gives BASIC access to the internal clock. This Is updated at each 
nberrupt by software. It can be used to keep time, display the time 
calculate elapsed time, and perform processing for timed intervals. ‘ 


Syntax: TI and TIS resemble variables, and ma 
§ , y be access b , 
assignments, as in PRINT TI$ or TX=TI. In each Hasrike mene: Ti or Tk 
is specifically looked for, and, if found, processed by a set of specia! 
routines. Tl and T1$ are not stored in the usual RAM area for variables 
Instead, they are generated when required from three bytes which make : 
yp the jiffy clock storage area. For this reason TI and TI$ are not 
eywords, and ANTIC for instance is a legitimate BASIC variable. The 
enclosed TI is ignored. ST,DS and DS$ are processed similarly. ; 


Modes: Direct and program modea are both valid. 


Examples: TI$#"130500" 
100 TI$=H$ + M$ + 89 


2600 T=TI 
210 IF TI=-T<120 COTO 2120: REM 2 SECOND DELAY LOOP 


1000 PRINT LEFTS(Ti$,2) “:" PRINT MID$(TI$,3,2) “:" RIGHT$(TI$,2 
8260 TES«"000000": POR J=O TO SE9; IF TIl=600 THEN J=9BS; GOTO 6600 


6000 NEXT 


TI$ can be assigned a value; TI cannot. The 
; : value must be within th 
haa range {and "240000" is accepted}. The first two examples show 
i . The string must de of length 6, and leading zeros must be included 
pear one ka’ aoe to the hhmmss format. The time is set to five 
e afternoon in the first example; in th 
of the time should be a two digit number. : a ierenat nt Ea 


The third example shows a two second delay ‘oo; 120 jiffi 

seconds which gives 2 seconds). Some CBM aanale hive te aracutaly 
worded warning against this construction, which is repeated more 
comprehensibly in Osborne/Donahue. The point lg that T! is not a 

Fei rinralpan increasing function. Ef you're very unlucky it may just happen 
© change from the equivalent of, say, "235940" to "000130", so the delay 
loop wil! be rather longer than intended. 


ae fourth example prints the time In hours, minutes, and seconds in 
ioe format: hh:mm:ss. Many routines have been written to present 
attractive graphica versions of the time, almost always as digital clocks. 


Finally we have an example of the ctock timing a loo 

. At the 
clock Is reset, to avoid any possibility of thettoent foes hour irae ne 
tadvainn, We set up a huge toop with an urbitrary terminating vulue, 
ia a test-and-exit routine which Is called each time the loop repeats. 
: set for 19 seconds In the demonstration line; of course if the contents 
of the loop process slowly thia time may well overrun. 


Notes: [1} 
; Three bytes hold tha jiffy clock; 141-143 In BAS 
ara sume to 2ec0 on awitching on the muchina, Rae Ore en 
INT 256¢256¢PEEK(141} + 25€*PEEX(149) + PEEK(143) in the 
j AAMO vA 
aoe erie wer from Tt by a teng routine involving a tehle of vuluaa 
rH ate 4 related to Tl by the fullowing formula, whlch conyerta TIS 


Pp 
MINT B04 (3800°VAL(LEFTS(TI9, 2}} *SO*VAL(MID$(TI9,3,4)) +¥ALCAIOHTS(TI$,2))} 
BASIC 1 umes locations 200-202 for itn JIffy clock. 
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{2] The clock update routine is called from the interrupt routine. All ROMs 
use SEFEA in the kernel’ jump table as the clock update routine, 90 if thls 
is repeatedly called the clock will sdvance at an abnormal vate. There ia 4 
software ‘correction clock’ included in the implementation on ali ROMs. Two 
locations, treated as 16 bits, are successively incremented at the same time 
as the clock itself; however, when it has counted to a certain point, it is 
reset toe zero, and the clock is aot, on that occasion, incremented. Every 
623rd interrupt does not increment the clock; the interrupts happen about 
1/6% more than 60 times per second. The routine has a further feature, 
connected with the STOP key. Obviously, to implement a key which is able 
to stop @ program at any time, it is not sufficient to leave the key's ASCII 
value in the keyboard buffer, because until there is a GET or equivalent, 
it wilt be ignored. It would be possible to cause a stop key to generate an 
interrupt of its own. But since the PET has interrupts continuously occur- 
ring, $FFEA not only updates the clock but also, in a short piece of code 
near the end, stores the keyboard PIA contents in zeto-page ($9B in 
BASIC>1}. Now $FFEi,the routine to test the stop key. simply has ta look 
at this location to determine whether STOP has been pressed. This is the 
reason that a change of IRQ address can turn off the clock and the stop 
key simultaneously. 


{3] If the interrupt disable flag is set for any length of time (the 6502 


command is SEI) the clock will lose time. Compu/think disks and the screen 


acroi! with BASIC<4, for example, both do this. The elock cannot therefore 
be assumed to be completely accurate: in any case, because 1/60th second 


is the smallest quantum of time that T{ can deal with, decimal points beyond 


the second are meaningless. 


[4) TIME and TIDE and TIMERS are a few of the many possible equivafent 
names of these variables. 


(5] With a little jiggery-pokery we can assign any value to TI, and any 
atring to TIS, by evading the normal mechanisms for checking these 
variables, (The same trick can be done with ST, DS, and DS$). 


10 TIS="AHA!" 
20 POKE 1084, ASC("R")+128 
30 PRINT "T1$2"; T1$ 


Spacing is important with this program, which does not use a VARPTR type 
of function. Old ROMs will require POKE 1085. (Line 20 pokes ASCII of 
I to replace J. The extra 124 sets the high bit, to distinguish T1S from 


Tl). 
Abbreviated entry, Token: Neither of these are applicable. 


: There arc three fragmented parts to the oporation of Til and TI3. 
aay he routine to caulene TH cheeks that the string contains only ASCII 
numerals and ia six of these charueters long. If these constraints are 
satisfled, the value of the string is calculated, and the result left ite 
accumulator #1. The most siynificant thren bytes are transferred into the 
clock area, where they are incremented with every interrupt. 


(2] & {3] A routine In needed to assign the value of TI$ to # new string, 
to accomplish T$-Tt$ for example; snother routine allows numeric assign- 


ments, for example T2T1+60. When there detuiis are corrict, TIS is “ALIA! 


ROM entry points: 
{1} Awaign TIS: 
BASIC 1: SCHDO@ (51423) 


(2) Aewign etring to tise: ?[3)Aenign puseric var; 


M2243 (52803) $9CRT1 (32840) 
BASIC 2: $CHEF (31419) FCEZE (52782) WEGO (32492) 
BASIC 4: $O9TZ (47474) SBFAD (49065) $BPFS (49139) 


The clock update routine, SFFEA, calla those ROM subroutines: - 
BASIC 1: S#7Id (83280) RASC 2: 97720 (87271) RASIC 4: SF76K (43336) 


“The interrupt routine which tests @ 
occurs 60 timea/serond with 4 acreen aochinegs, 


The latte 


TE.G, J3A CERES JSR CALF (RASIC 2) printe TID. Que 1PUG newaletter, July ‘#1. 
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Lep, chacka the Seyhourd, and updetaa tha ebock 
60 times/ssecond sith £9" machines. 
rt have a software cheat ehich Inceements the clock twice avery 3 bntecruphe. 


TO ee ee mR tie NN A Raley NE NEEL. 6 2 


as 


75, 
its) 
at 
tries | 
"28, 
“ay 
Sears 
i re 
Fy 


Sr Mant oe as “reat tnttetey seerenprner ame = 


Soper mene 


oad 
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TRACE 


BASIC ufility unavailable with CBM 


PURPOSE: a TRACE is a diagnostic routine which provudes information on the 
way @ program runs; this information is collected during an actual program 


run. 


The facilities provided by trace routines vary; some print only 


linenumbers, some fist lines during execution, some monitor particular 
variables or commands only. 


Versions: 


Brett Butler's relocating loader is a well-known trace; it appears to be in 


the public domain, and is listed in ‘Pet Revealed’ and elsewhere. [t displays 


sta 


tements in reverse at the screen-top. Several traces display linenumbers 


only. Brad Templeton's Power chip has a routine somewhat similar to the foll- 
owing, which uses the CBM's own LIST function to print lines. Readers may 


CANON eeN-o 


10 
14 
12 
30 
4c 
sa 
60 
70 
ed 
230 
240 
250 
276 
260 
290 
3190 
420 
330 
340 
3590 
360 
370 
REM 


DATA 169,0, 133,48, 133,50, 133,52, 169,0, 133,49, 133,51,133,53 

DATA169, 76, 133, 129, 169, 35,133, 130, 169,64, 139, 131,96 

DATA 169,55, 133,129, 169,233,133, 130, 169,48, 173,134,96,0,0,0,0,0,0 

DATAO, 255,90, 141,-572,142,7571,140,-570, 174, 16, 232,224,254,208, 13,236 

DATA 1B, 232,240,251, 173,-569, 73,255, 141, -569, 174, -569, 240,119, 224, 253, 208 
DATA127, 236,18, 232,240,251, 160,0, 140,~568, 140, 158, 0, 32, 228,255,240, 251,24 
OATAIOS, 198, 141, -S65, 165,54, 164,55, 205,-567, 206,5,204,-566, 240,77, 172 
DATA-568, 208, 184, 174, ~565, 142,-564, 169, 255,32, 163,229, 236, -564,208,246 
DATA 162,0, 181,0, 157, «256,202,208, 24d, 32,87,226,162,79, 169, 32,157,9, 128 
DATA202, 16,250, 165,54, 164,55,141,-567, $40,-566,133,17,132,18,32,44, 197 


DATA32, -374,162,0, 189,~256, 149,0,202, 268, 248,32,93,226, 173,7572, 174,-571 
DATAI72,-570, 76,10, 225,224, 127,209, 149, 142, -568, 236, 18,232,240,251,120 
DATA174, 158,0, 169,9, 157, 111,2,88,240, 164 

T=PEEK(52) + 256"PEEK(53} 
L=T-614 

FOR J = L TO 14239 

READ X%: IP X®<O THEN Y¥*#k®*T; 
POKE J, x* 

NEXT 

x= @ 

POR J = Ut240 TO Le357 

POKE J, PEEK (K+50654) 
XeX+1: NEXT 

POR J=L+251 TO L#253: POKE J, 234: NEXT 
POKE L+315, 96 

Ao" L/256: 2 = Ll - X4*256 

POKE 49,Z: POKZ 50,2: PORE 52,2 

POKE 49,X%:POKE 51,X%:POKE 53,X% 

Xe (0450)/256; 2 = (L451 )-k0"256 

FOKE U+2i, 2: POKE L+25, X& 

ME = L/256: Z2 = Lb + x9*256 

POKE L+1, %1 POKE L+9, X% 


X¥=¥/256: Z=a¥-X8*256: POKE J,Z: Jas+1 


TRACE FOR BASIC 2 
("UPGRADE ROM’) 


RE FeO HA dA HE OE OE ATION EEE OO OY 


PEM «+ 
PEM 4 
PEM 
PEM 
PRINT 
PRINT 
FEIT 


PRINT 1" 


PRINT 
PrtE 
PR UT 
Pr THT 
PRINT 
ENG 

WE t4 

PPM Dee ft 


FINALLY, PRINT OH/YOFF ADOPESSES [ti DECIMAL ANG HEADEC IMAL ” 
AHO INSTRUCTIONS FOR LSE » 


PORE EHH EERE HEE HH HY OO ARE > ehh edo fm A ee 


“Jemig BASIC <4 “TRACE” BY RAY WEST ” 
“ SEHRELE 1 . 
"MILGMBLE . SVS" sl 429 
FRTHT "sAYE FROM 


SSL 


rosa "to" » £s380 
C633 SG COG, PRIHT “ TO €"54 LeT-258e GASUB 6003) PRINT" 


“Ra INSTRUCTIONS ™ 
"eso 
">. 

"MUR THEN 22-9 
“@oPACEs 


PUTS TRHEE ON/OFF CH 
STMGLE STEPS UHTILa- 

SETS SPEEQO FOR STEPPING. 
FOF FAST TRACE. 


MAL TO HREAOEC INO. COMVEPSION ROUTINE FOLLOWS 5 


Le.7409965 EOP Jet 104 cel IPP IT CHP RAE OL (L299 M7 9 LL SOCL-LED IHENT ARE TURE 


+ 
~ 


a a Ea on Ee eee mE aren eee Pee 
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Like to try the new trace, which I've listed here as relocating loeders for 
BASICS 1 and 2. It is controllable from the keyboard and also uses the PET's 
own list subroutines, so lines sppear on the screen top just as they do when 
LISTing. In addition there is a single-step feature. The program is discuss- 
in Ch. 13, section 13.4.3. Note that the instructions are shown on the screen 
by the same routine in each version, so I've printed them once only. 


-<OCATINC LOADER FOR BASIC 1 TRACE 


DATAIS9> Oo 839-1350) L33e AST) 13939-1394. thF- O0199s t31- LAG, 1394-1393,195 

DATA 169-76) §33-211+169038- 193.2227. 149764) 2139+ 219+ 96 

DATA 169+ 5S6e 43:3) 2LL: £69> 29GB 133+ 212) LF 2 4B, 1393 219+ FS Gs 0,01010+0 

DATA 0925510. 1411 -570) £42¢ -S691 1401 -S6801745 18+ 232> 2242 254+ 208s 132 236 
DATA 18) 2321740. 2525173) -357 +79 25521445 -567017 Bee S674 2400 £191 2246 259s 208 
DATA 2127) 236: 181 PAZ 240r 2512 1600 0s £40 -$66) 1400 19, 26922 2283 2555 24012511424 
DATA 105+ 1498) 141» -S63> 16S) 196s 164,137» 205; -565r 208+ Sr 204, -SAd, 2407775172 
DATA 566) 208; 18471745 -5630142+ ~5622 169) 255+ 32+ LFS + 229s 298+ -S621 2081 246 
DATA 162+0>£81,0+ 157+-256s 202) 208+ 248; 32s 105) 224+ 162) 7911697 92515770128 
DATA 202) 16> 25011651156 164+ 1372 £412-$651140+ -S64s 199+ 8.1392. 9+ 392-394-197 
DATA 32) 372) 1621 Or 189+ - 2560 1491 Or 202s 208) 248s 32s 21Fs 229) 173s -57 00 174, SEF 
DATA L72¢ —-5b8s 7s £982 224) 22471271 2084 L497 242, - Shh) 236s 18+ 232s 240) 2520120 
DATA 174)13> 2+ 146920: 257) 14521842 2402 £64 


REM 
REM Hee REE EEE RAPER ESHER ARES EE SEREAAEHRAEEHREEHE EER AE 


REM #THESE DATA STATEMENTS SET UP THE CONTROL PART OF TRACE (NO LIST bia 
REM # 
REM #AND LINES 30-70 POKE MEMORY, RELOCATING ADDRESSES MARKED BY NEGATIVE* 
REM ie ak 9 4 ee A EE Aa a EE 
REM 

® PEEX(194) + 256*PEEK(135)} + REM T * CURRENT TOP OF MEMORY (NLD ROM) 
Ls T+ 412 a REM ENTIRE TRACE 15 612 BYTES LONG, 
FOR J = L TO 1.4239 : REM DATA STATEMENTS OCCUPY 239 BYTES: 
READ X30 IF X(0 THEN YaxX4Ts X¥a¥/Z541 Za¥-XX#2541 POKE JrZt Judel 
POKE J+ XX 1 REM POKE DATA (OR HIGH BYTE, IF -VE.) 
NEXT 


REM 
REM aedeR EERE RES REPRE EEEE REED OEEERDRERPREESEEERE RHEE EECA EESHPOT EE EHE 


REM *® OLD ROM) MOVE §CS0$-8C44d8; NEEDS USR ROUTINE TC PEEK (BORING!) * 
REM # THIS ROUTINE WILL LIST 1 LINE WHEN MODIFIED SLIGHTLY:* 
REM FESR RHEE NER AREHE EERE EE EEKK EERE OEREEE RAE AREER EEN EEL RARE EEE 


33 REM 
98 REM ##8 USR SET UP IN CASSETTE BUFFER £2 (ROUTINE IS RELOCATING? #e0 


09 REM 

LO DATASZs 109+ 2197 165+ 160) 133) £78) L601 0.177 178s 168s 169s Or F2> 1204 2100 FE 
20 FORT #82470843: READK: POKE Ls Xs NEXT e POKEOs 76s POKEL) SOsPOKEZ+ 9 

30 kX = 0 

$0 FOR J * 14240 TO L+356 

50 POKE J ¢ USR (%+50645) 


VwVevVvNrvVewnmwaN ee 


BNR STSY 


70 XeXel) NEXTe (REM X COUNTS POSITION OF PEEK IN ROM 

90 FOR JeL+25L TO L+2531 POKE J: 234 +NEXTi REM 3 NOP OPCODES ERASE CRLF 
7O POKE £4313) 94 : 1 REM FROM ‘LIST’. THEN RTS. 
00 REM 


OL REM PORERHHASEE ERI SEERESEN SEEPS ER EOHHEES HOR AEH EEES ERS HONORE H HH ENED 
02 REM # SET ENO-GF-MEMORY POINTERS BEILQW ‘TRACE’ TQ ENSURE NEWLY # 


03 REM # LOADED MACHINE-CODE DOESN'T CET OVERWRITTEN, ° 
04 REM HSHRSSSHEHEAHHEESHSHHEEHSAHRREPHERASSHTHORANFOHSOHHKS EE SERERERARS 
03 REM 


10 XX% = L/236) Z = bk = X¥#2366 REM HIGH AND LOW BYTES OF END OF MEMORY 
20 POKE 130-21 POKE 132,21 POKE Late? 

3O POKE 1354.%%0 POKE 133+X%¢ POKE 135,%% 

40 XX w{Lo$i)/256c 2 © (L4Si)-x4e256+ REM HICH, LOW BYTES OF HEDCE 

SO POKE Le2i+ ZL: POME L+25> XX: REM PUT WEDGE ADOCRESS INTO ENABLE, 

60 XE = L/Z540 Ze L + kXe2361 REM HIGH AND LOW BYTES OF NEW MEMORY TOP 
70 POKE Leds Zt POKE L+9, X% 4 REM PUT NEW MEMORY TOP INTO ENABLE. 


00 REM 


| 


| + TaN. Sprite = 


2A le AE A I ee 


Ret ee re eee pee - 


| 
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UNLIST 


System command unavailable directly on CBM BASIC 
PURPOSE: To prevent LISTing and editing of BASIC programs to reduce the risk 


of unatthorised capying or modification. 


Versions; Some microcomputers (e.g. IBM's) include commands of this sort. Their 


success lies in the relative inaccessibility of systems software and operating 
system knowledge generally. It seems unlikely that foolproof protection is 
possible with any widely-sold microcomputer; it is only possible to go some 
way towards it, relying on temporary expedients and perhaps legal measures. 
Many BASIC programs on sale make no attempt to conceal their inner workings 
but nonetheless methods have been tried;* a collection of suggestions 
follows, arranged roughly from simple ta complex. 


(1) Inclusion of characters which stop the LIST or clear the screen or affect 

the printer, in either REM statements or dummy lines, gives some minimal LIST 
protection. A program loaded from another, with the atop kev disabled may 

be made tiresome to get at, by including screen editing characters in its name 

go that it takes some effort to load directly. !n this way, a directory (or line 

of a program) can be made rather misleading; parts of the name may appear 

on different screen lines, say. Unfortunately, even if a program were made 
completely anonymous, hardware reset methods (see Chapter 13) may be able 

to break into the program: the IRQ and NMI vectors therefore need to be 
changed to prevent this. 


[2] A promising approach is to modify BASIC as it runs. A self-modifying 
program might change its own link addresses or linenumbers or zero page 
Pointers. Practical Computing had some correspondence on the idea of making 
te firet line, numbered 0, point to itself. POKE 1025,1: POKE 1026,4 does 
this. 

Another idea is to change the link address of the first line; LIST therefore 
will go astray on the second line, the first still listing normally. Unfortun- 
ately, the [nk addresses are also used by GOTO and GOSUB when searching 
for earlier linea, so these commands need prefacing by a correcting POKE, 
like this: 75 POKE 1025,0: GET X$: IF K$="" THEN POKE 1025,34: GOTO 72 
where 34 (or whatever) ig the correct link value. The drawback is of course 
that peeking or using the monitor soon enables anyone famillar with the idea 
of link addresses to calculate the correct poke or pokes, 

A modification of this idea Ig to include zero bytes within lines so that 
invisible bits of BASIC can (say) call machine-code hashtotal routines to 
detect any changes in the program, Hidden BASIC though is rather vulner- 
able to editing and tends to reappear. 


[3} Overlong program fines {length exceeding 255) can be used, and the 
resulting program ls genuinely uniistabie; LIST can't handle it. Some other 
commands will sino come to grief, e.g. READ; the Ideal candidate for such a 
ling ls a full screen of data printed by a huge line. Such a line at the start 
of a program will stop LIST, unlesa zero bytes are reinserted with linka, 


[4] A method reportedly prevent in & prototype ‘Toolkit’ worka as follows: 
(See Liv, Soft. Gaz. Dec '86}: Each Ilne begina with 5 colons, like thia: 
10:::::A25. Or Ln fact any five characters or tokens will do, The UNLIST 
Pute a zaro byte after cach linenumber; LIST stopa at the zoro byte, so onty 
linanumbers list; but RUN interprets the zero as end-of-line, and continues 
4 byten on, ao the program runs auccesafully. This HASIC subroutine wilt 
put in the zeros; it assumes that 5 charactere aro present, uniike UNLIST an 
quoted which puts these In for you: 

80000 ¢::::401028; YOR Jel TO 128; IP PEEK(A+€)>4 THEN PORE A+4,0: 

AwPERE(A)+294*PERK(A+1): NEXT 

60010 :::: END 
Thia is however very almple to ra-lst; this direct-mode ilne will POKE 
colons Dack sgali: Ao1095 :-FORS=1TO1EA ; POREAS4, GR: A-PEEK(A)+ZO06¢PRER(A+1): 
IF AcsO THEN MEET .AO the method in not a great success, Thea best you can 


¢, eh aes a Eyes e ys See ne ib eee Sorts Sm kh Ne aE aes, 
petravare Protection includes the ‘dongle', plugged inta the back of the PET, end 
Fladically oheched by the software, Such protection is often easy to remove. 
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ia to sct a few traps in the hope they won't be noticed, such as including 
spurious BASIC in the four ignored bytes which are revived by relist. For 
Instance, 100::::AA750. when ‘UNLISTED’, is translated as A=50; on relist, 
unless the A is edited out, the program will run incorrectly. 
200:ANEWBCA=50 is another version of A=50, since it is preceded by four 
bytes, one of them a taken. On relist and RUN, this line will of course erase 
the program {or at least its pointers), 


[5] Compu/think disks have a security device which works like this: to use 
these disk units, an initial SYS call changes the CHRGET routine so that 
BASIC is intercepted by the "Diskmon' ROM. Additional commands are then 
identified by a leading '$'~ $D,1 for instance is the directory command. The 
extra commands include load - $L,1, "PROG" typically. Throughout this process 
CHRGEY remains modified. Now, if an asterisk is found in location 1034, just 
after the start of BASIC. (-$040A), only three commands are allowed, RUN, 
and two specia! commands which clear the memory and run machine-code. * 
LIST or SYS or any other direct command returns only READY. Moreover, 
linenumbers cannot be erased or edited: typing 100 Return won't delete line 
100 when the machine is set as described. Setting the BRK vector to print 
READY makes this system, so far as memory storage is concerned, pretty 
foolproof. All that's needed is a REM statement in the first line, 90 an extra 
asterisk won't matter, then POKE 1034,42: $5,1,"PROG" and the unlistable 
program is saved on drive |. (42 is ASCII fer ‘*), When this program is 
loaded, the intercepting routine tests direct-mode commands and rejects all 
except the three mentioned. This process is adaptable to other systems, but 
only with hardware add-ons, or with some software method for ensuring that 
@ modified CHRGET is obligatory, since otherwise a program can simply be 
loaded and listed, asterisk and all, as usual, The weak point of such methods 
fs located in the disk storage, rather than RAM storage. [f the disk storage 
system is understood, it is possible to load a relevant part of a program, 
modify it, and replace it on the disk. See Chapter 6 for concepts and methods 
applicable to Compu/think. 


[6] The most thoroughgoing systems for concealing BASIC rely on machine 
code routines. Disk-based BASICs, which are loaded into RAM, can of course 
be modifled in situ; LIST can simply be deleted, or the operating system 
changed. In CBM BASIC this would require a change of ROM. Insteud, let's 
consider waya of scrambling BASIC so that it will run, but not LIST. Each 
line may be written like this: LINENUMRER SYS XK: BASIC LINE: sys ¥, where 
everything after SYS X is stored in coded form, ineluding SYS Y. In this 
way each line can be decoded before execution, and encoded on teaving, with 
some exceptions like GOTO statements. An encoding alguritnm has lo be fairly 
subtle: adding t to euch character would be easily undone. Typically, EOR 
of severul variables gives a repeatable offset. More elegantly, this scrambling 
and unscrambling process can be carried out by rewriting RUN. The major 
loop controlling RUN processes singto statements individually, and schemat~ 
feally looks like this: - 


JOR CLR 

LOOP TEST STOP 
LOAD CURRENT CHR. 
BNE NEXT ST‘MENT ‘ 
TEST FOR END; IF NOT, 
UPDATE CHRGET & 


A similar routine may be put into 
RAM where a SYS cull will run 
BASIC. One Ja then (ree to insert 
decoding / coding routines before 
and after tho statement -peocessing 
eall, This isn't very easy: colons 

LUNENUMAKR ETC. und zeros in the original must be 
NEXT QTMENT JBK GET CHA FXTCHES TOKEN preserved a4 special cases, and 

JBR ACTION TOKEN (OR ‘LET’? o record must be kept of the pum~ 

IMP LOOP PROCESSES : ORO bar of bytes altered by decoding. 
A teat for direct-mods, with a ayatem reset if found, cun he put Inte the IRQ. 
There are, of cours, many other posaible attacks on this problem. lerhips 
the last word should go to Tommy Turnbult: ‘Wo've had ail kinds of protection 
hero, The longest teok an hour ...' 





9G, ‘which should run machine-code, contained . oug which aften cauaed Feturs to 
the monitor, adjusting the program's length until PRIK(42} 094 pravente this, 


Nee a arebiiamamnaimmetiaien santana netelemhantanetbendemterhiieaiasntaneinte anee-eeintehens aenean anh cetera ana aca scat caman aatineiaantinainn candies dando asicansamemaneea 


CREEP RAEI ee PCR TRAN Mas IN ER eT at 


8 A een semitr oman Hh fre BH ‘ate, 


d 
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USR 


BASIC arithmetic function 


PURPOSE: Arithmetic function calling user-written machine code. Some knowledge 
of machine code is necessary to understand this function. 


Syntax: USR(arithmetic expression). The expression, when evaluated and,if need 
be, rounded down, must fall within the range 065535. fn addition, locations 
02 must contain valid machine code: trsually, because of the small space in 
tero-page, a JMP to the user's own routines. This is a function, and may 
be used validly in such statements as PRINT USR(345), X=USR(2), Y=USR(X)-. 


Modes: Direct and program modes are both valid. 


Examples: [1] See PEEX for details of a USR function which acta like PEEK in 
BASIC 1. it can be used ins statements like: POKE X, USR (X-1)} which 


are not valid in BASIC 1l‘'a implementation of PEEK, due to a dug. 


Syed machine code routine listed here and $0000 JMP $627A 
called by USR displays the contents of floating 

point accumulator #1 at the top teft of the VDU. parasbhs aan eee tl 

6 bytes are poked directly to the screen, so 0 S276 LDN Bere 
appears as @, i as a, 248 b, and so on, when $0272 STA $8000, x 


in lower case mode. Since USR. in common with eo2et DEX 
ali functions, puts the argument into this agae4 Bt a7: 
$0284 RTS 


accumulator, its contents and method of storage 
can be examined. For example:- 

USR({0) gives @09@0@ or 0009060. 

USR(L) gives [Adjaaea or 129 128900 0, 


[114] $0000 Jur $CD6F ; THIS SXAMPLE 15 SGM IN BASIC 4 


If you have BASIC 1, the USR replacement for PEEK is very useful. The 
second example (BASIC>1 only) displays the contents of accumulator #1 in 
separate bits, which is of interest to those readers who want to learn how 
NMoating point numbers are processed. The final example ia a special case 
of a function, and shows how USR can access routines in ROM; in the given 
case, USR{X) returns the same value as SGN(X)}. Experienced machine cnde 
programmers may be able to write their own mathematicat routines along the 

_ game lines as those of Microsoft; if so, they will be callable from BASIC by 
USR. It is a safe bet that this is not done often, 


Notes: [1] Bytes 0-2 are initialised on switchon to print 7ILLEGAL QUANTITY 
ERKOR, s0 USR without a modified instruction in 02 gives this message. 


[2] 8¥8 0 carries out the same instructions as USR(0), but ia a command, 
not a function, and so cannot be assigned or printed. 


{3] Locatlons 0-2 need not contaln a IMP. An RTS (=$60, 96 decimal) for 
example gives USR{N) the value N. (Or to be exact, INT(N)}. An indirect 
jump Is vatid, BRK (:0) in location 0 will cause the monitor to display the 
contents of Its registers when executing u function. 


Abbreviated entry: uS 
Token: $87 (183) 


Operation: The value of the argumant ia computed and validated and put Into 
floating-point accumulator #1. Thia ia normal behaviour on encountering a 
function, The difference (a that the addreas now jumped to Ia $000. Thia 
In an aay function to add to BASIC, since once the function-handling 
roullnes are written, hardly any more work is needed to Incorporate USR, 


ROM entry points: 
All ROMs jump to $0000, 


a ale i al nar Gt 


Dhan tietadhienanaiaialed 
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VAL 


BASIC arithmetic function 


PURPOSE: Computes the ‘value’ of a string or string expression: the entire string, 
Or as much as [s syntactically acceptable, is converted into a number. 
This function is an important converse of STRS, enabling calculations ta be 
performed on a quantity which, perhaps for formatting reasons, is held as 
say " 123.45" or as "1, 239E04". 


Syntax: VAL(string expression}. This Js an arithmetic function of a string argument, 


The string expression must be valid; it can consist only of literels, string 
variables, and string functions concatenated by +. Its maximum permissible 
length Is 255 characters. If spaces are included, when using BASIC>i - for 
instance V AL(Q$} - an array VA() will be assumed, and a ?TYPE MISMATCH 
ERROR generated whenever this code is encountered. 


Modes: Direct and program modes are both valid. 
Examples: PRINT VAL("'L29,456") :B2M RESULT I9 123.456 


PRINT VAL("-127") ;REM ~127 

PRINT VAL("1,2 E2"} :REM 120 

PRINT VAL("E") :REM 1 (i.e. 1 BO) 

PRINT VAL("1000000000000") ;REM 1E 23 

PRINT VAL{LEFTS(TI$, 2}) :REM 0 TO 24 (1.0. the hour) 
PRINT VAL ("1504200") :REN 150 

PRIST VAL("2.2.3") :REM 1.2 

PRINT VAL(¢"") :REM O 


PRINT VALC"1L23° + CHA$(O} + "456"):REM 133 
408 J=VAL(IN$): IF J¢82 OR J>90 THEN MS$="WRONG YEAR" :GOSLBIOO: GOTO400 


Any string, including the null string, which evaluates ag zero, is accepted by 
this routine, but validation is only implicit, and no error message is printed 
if a string has non-numeric characters in it. This can be very convenient, 
but equally may be a source of bugs. For this reuson most of the examples 
are direct mode print statements. But, like ASC and LEN, VAL may be used 
freely in arithmetic expreasions; the validation line from an input routine is 
an illustration. VAL will accept spacee,+,-,E (unshifted only), the decimal 
point .,and of course 0-9. The validation proceas ls intricate and flowcharts 
for it have not been published; it is not particularly important to know the 
Precise method of validation, though. The most significant fact is that the 
firat unacceptable character terminates the VAL. There are three liner in 
the demonstrations which are actually terminated like this, ending when + 
and . and CHR$(0) are encountered, respectively. Remember that E refera 
to a power of 10, a0 1.2E2 ls the same as 1,2 * 107 or 120, 


Abbreviated entry: vA 
Token: $C5 (197) 


Operation: Most of the processing is carried out by a general routine to scan a 
string and convert tt Into a floating-point number In accumulator #1. The 
remainder ls housekeeping: the mode is changed to sumoric, and a length 
of zero causen exit, with VAL assigned zero. [f, as lx usual, the string has 
non-zero tength, the current CHRGET adress is anved, and 4 puinter to 
the etring put ln its place, This is because the conversion roution seins 
the atring using CHRGET. A pointer ta the end of the stcing is set up to. 
Both accumulators and LO bytes of additional atoraga are used hy the main 
routine; thla user CHRGET to Ignore spaces and fateh 0-8 (Thid ln signalled 
by a clear carry bit alter CHRGET), E and decimal polat are tookud for; 0 
are + and -, In both their ASCII form anil as tokendwed keywarda, The 
routine calla oxtra routines to perform such tasks a4 multiply the uccumul- 
ator by 10, and add the contents of A ta the Momting polnt accumulator. 


NOM entry paints:0491C1: 40088 (34017) BASICS: $0687 (54019) MASICA: ECRED (62427) 
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VARPTR 


BASIC arithmetic function unavailable directly in CBM BASIC 


PURPOSE: Finds the actual focation of any variable in memory, after It has been 
set up in the normal way on running. 


Versions: Although BASIC‘s routine to seek variables is well known, there have 
been few attempts to write actual! routines embodying it. VARPTR is Tandy's 
name, end their BASIC is the only popular one with this command. My 
routine points to the name cf the variable, so that the location indicated 
for AA$(6) is the start of AA${}, and is the same value as that returned by 
AA${(10). To make the routine usable from within BASIC, the value must be 
assignable, rather than accessible only by printing, say. It therefore uses 
not only the variable search routine but part of LET. 


The syntax is: SYS start address: sought variable: numeric variable. 

The routine is relocatable; typically, SYS 634:4B5:X illustrates the syntex. 
X holds the value of AB$'s starting point in memory, at the time the routine 
was run. Array varisbles of course may move up memory when new simple 
variables are defined, but this cannot happen with simple variables. 


Example: 10 L¥=t5 
20 SYS 634:L4:X: REM X NOW EQUALS RAM LOCATION OF L&E 
30 FOR J = I TO X48: PRINT PEEK(J);: NEIT 
40 END 


When run, this program prints out; 


204128 09 i585 GO@ O 0 
Ch « 0 i6 holds the name and the value of this tuteger wariable) 


Machine code: 


BASIC t: JSR $00C2 BASIC 2:~ BAS(C 4:~ 


BASIC 2,4: JER $0070 


JER 3CF7B JSR SEARCH 9cr6D C125 
LOY $AE LDY $5C 

LDA JAF LDA 95D 

JBR $D276 J5H FEFLT $D26D 9c48C 
JSR $00C2 JBR $0070 

J8R SCPTB JGR SRARCH scPréD 9125 
STA $98 STA $46 

STY $99 BTY $47 

LDA $5F LDA $08 

PEA PHA 

LDA $5E LDA $07 

PHA PHA 

JaP SCOBZ JP ASSIGN s8c2 $8045 


Notes :(1] This routine won't find Ti, TI$,5T, or (in BASIC 4) DS or DS$, since 
these do not exist in RAM as ordinary variabies do. 


{2] A shorter routine can be written which prints the values without the 
additional assigning; this can be valuable when inspecting variables in 
direct mode, Reptace JSR FXFLT, which converts a 2-bytea number [nto 
floating point farm, by « print routine. tn thls way onty 13 bytes ia 
enough for the routine - everything after the fifth instruction can be 
ignored. The replacement 1a: 

BABIC 1: JMP $DCOF / BASIC 2: JP SDCDS / BASIC 4: JMP $craa 


Se ce re 
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VERIFY 


BASIC system command 

PURPOSE: Compares a stored memory dump on disk or tape with the equivaient 
contents of RAM. If they are not identicat, ?VERIFY ERROR results, 
Usuetly VERIFY checks BALIC programs which have been SAVEC; but 
other memory dumps, e.g. machine code routines, may be VERIFY 'd. 


NOTE: VERIFY reads the program or dump specified, ond compares it with 
the contents ef RAM, without loading it into RAM. Consequently, VERIFY 
only epplies to programs ond other memory dumps: it cannot be used with 
ony form of data fite which is output from a buffer. 


Syntax; The syntax is identical to that for LOAD, including ali the differences 
between tape and disk syntax. 


Modes: Direct and program modes are both valid. VERIFY from within a program 
may be used to check a save to tape or disk; a message requesting the tape 
be rewound is necessary with cassettes, Unlike LOAD, the operation of 
BASIC is not reset; after'OK’ the program continues normally. 


Examples: 10 SAVE "THIS PROGRAM": REM TAPE UNIT #1 ASSUMED 
20 PRINT "REWIND FOR VERIFICATION - ANY KEY TO CONTINUE" 
30 GET X$: IF X$="" GOTO 30 
40 VERIFY 
50 REM ... REST OF PROGRAM ... 
SAVE "0:5TH VERSION',6 <:REM TYPICAL DISK SAVE 
VERIFY "0: 5TH*",6 :REM TYPICAL DISK VERIFY 


PRINT#15, "VO": AEM THIS IS ANOTHER DISK FORMAT. ¥Y IS ‘VALIDATE’, 
OR COLLECT’ (q.¥.); THIS 15 NOT THE SAME AS VERIFY. 


Notes: {1} If you examine the ROM routines you'll find that VERIFY is largely 
identical to SAVE. However, if a flag ($9D BASIC>1, $020B BASIC 1) is set 
non-zero, the program is read but the bytes which are input are compared 
with RAM contents; if they differ, ST is set to #410 (16) and ‘VERIFY 
ERROR printed. Otherwise, OK appears. When using ROM routines it is 
good practice ta set the flag, otherwise a 'SAVE' may only be VERIFYing. 


{2] Some HASICSs, e.g. Appie. have a verify atatement which applles both 
to data files and programs, but Commodore's doesn't. 


[3} VERIFY, Sike LOAD, defaults to cassette #1, or disk unit 6, 
Abbreviated entry: vE 
Token: $85 (149) 
Operation: See note [i] 
ROM entry points: VERIFY ls a ‘wernel' command; Its jump address ls SPFDE. 


BASIC 1: $F4BB (62651) 
BASIC 2: $F4B? (62647) 
BABIC 4: $FAFC (627103 
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WAIT 


BASIC command 


PURPOSE: Causes BASIC to wait until the memory location specified by its first 
parameter has one or more bits configured in a way specified by its other 
Parameter{s). Any combination of bits within the location can be tested; 
when any of these bits takes the sought value, the wait is over. 


5: BASIC keywords 


Syntax: WALT arithmetic expression 065535, arithmetic expression 0-255 with 
optional third parameter ,arithmetic expression 0-255. The optional third 
parameter defaults to zero, as might be guessed. If the expressions do not 
yield integral results on computation, they are rounded down. 


Modes: Direct and program modes are both valid. 


Examples: WAIT is intended for such uses as handshaking, where some signal is 
awaited. If a program WAITs for a ROM location to change, or a RAM 
_ location which is not accessible to hardware or not updated by the 1/50th 
1/60th second interrupt, then it will either wait indefinitely, or not at all. 
WAIT should be used only with locations whose contents vary, therefore; 
the examples show this: 


WAIT 59410,1,% : REM WAITS FOR RVS OR RVSOFF 

WAIT 59410,4,4 : REM WAITS FOR SPACE OR SHIFT-SPACE 

1000 POKE 158,0: WAIT 158,1 : REM CLEAR BUFFER/ AWAIT KEY 
WAIT 152,1 : REM WAITS FOR A SHIFT EEY 

2210 WAIT 142,1: ARM RANOOM DELAY OF 6-8 SECONDS 


Because of the hardware-related aspect of this command, an instruction which 
ia successful with one hardware configuration may work differently with 
another. The examples ali work for BASIC 2, but the 8032 keyboard causes 
the first two instructions to respond to different keys, and BASIC 1, with 
a different zero page allocation, can't run the last three. Numbering bits 
ag usual 7 to 0, this is what these commands do: i. Waits untit bit ¢ of 
location 59410 is 0, ii. Waits until bit 2 of location 59410 is zera. iii. Waits 
until bit 0 of location 158 is 1. iv. Waits until bit @ of location 152 is 1. 

v. Waits until bit @ of location 142 ig 1. The first two commands’ location 
ig controlled by the keyboard PIA; the next location holds the number of 
characters in the keyboard buffer: this is updated during interrupts. The 
fourth again uses the PIA, and the fifth the jiffy counter for the clock. 


Notes: (1] WAIT is a little-used command and not a very useful one, except maybe 
Cor people with their own hardware addons. lt ig also rather difficult to 
expiain, Consider WAIT uddress,a,b. WAIT peeks the contents of addresa, 
performs exciusive-or with b, then AND with a. If the result is non-zero, 
BASIC continues; otherwise, the loop goes on, What Is the reason for this? 
To see the answer, let's consider an example: suppose we wish to wait for 
bit 4 af addresa to be off, or bit 2 on, [n either case we are happy for the 
Program to continue, but otherwise we stil! wish to wait. The first thing is 
to use paramcter b lo switch Olt 4, which it does by EOR with #O00L O00. 
§o with 6-16, bit 4 Is switched: now, when the desired condition occurs, 
bit 4 will be turned on. tf parameter a ls 40001 0100, the result of the first 
blt manipuistion ix ANDed, leaving a result which can be non-zero only If 
bit 4 was off, or bit Zon. So WAIT addresa, 20,16 Ia the sotution. 

80, WAIT address.9.8 watts uatil bit 3 im off; WAIT address,4% waite for 
bit 4 or bit 5 to be set to fs WAIT address, | waite for ble 9 to turn on. 


[2] WAIT 6502.n j4 Microseft's joke In BASIC 2 only. a-@ ta 295, 
Abbrevisted entry: wA Token: $92 (144} 


Operation: The parameters are computed and validated; the optional parumiter iq 
theckert for; then the address iy store? in ($11) in BASIC>L and the piri: 
Meters in $46 and $47 respectively, The stop key ds not tested for (SFT EL) 
80 the routings cannot be lsteerupted by preasing STOP. : 


ROM entey palnia: BAAIC1; $D702 (65042) BASICI. JOTIG ($8056) DABIC4: 3COHA (61554) 
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CHAPTER 6: DISK DRIVES 


6.1 Hardware 


Disk drives The disk drives we shall consider in this chapter use so-called ‘floppy 
disks’ as their 'media'. (Like ‘data’, in computing circles 'media’ is optionally singular 
or plural}. Alternative bulk memory-storage devices, notably sealed ‘hard disks’ or 
‘Winchester disks’, named after an IBM project, are coming into greater use, and CBM 
have announced and shown a medcl; nevertheless floppies are by far the most popular 
storage system apart from tape. Originally introduced as an alternative method of data 
entry to punched cards, by IBM in the mid-70s, the techniques were taken over and 
.used by microcomputers a few years later, In the process, IBM's carefully thought out 
standards were modified and to some extent dropped. For those not familiar with the 
concepts of floppy disks, there is an outline in the next section of this chapter, But 
the basic idea is similar to that of multi-track tape, arranged radially on a disk, like a 
gramophone record, so that any track can be selected without the long time delay in- 
evitadle when searching tape. The disks are often called 'diskettes', and the units to 
read to and write from them are called ‘diskette drives', though in practice it is usual 
to talk of the units as ‘disks’ - ‘Have you got disks?' These drives are made by spec- 
ialist manufactures, for example Shugart and Micropolis, and require fairly careful 
handling. They are usually packaged by the computer manufacturers, and end up in 
boxes and machines of widely differing sizes and shapes - Apple disk drives and 
Commodore's may contain the same units. All these drives, when looked at without 
thelr external cases, are quite similar. 

Typically, a drive unit has a read/write head mounted on rails, and 4 stepper 
motor which positions it opposite tracks an the diskette. The head is usually a ferrite 
and ceramic mixture bonded in glass; the step size is of the order of 1/40th of an inch 
To clean the recorded track there are ‘tunnel’ or ‘straddle’ erase heads to delete any 
recording within a short distance from the track. The actual width of the recorded 
zone Is something like 1/80 th of an inch. When a diskette is inserted into a drive, the 
elutch mechanism which grips the central hole has to position the diskette consistently 
to within this sort of tolerance; if the disk is also to be used with other drives, these 
too must be equally precise, or alignment errors will cause fallure to read correctly. 
The drive's spindle motor rotates the disk, which, because of centrifugal force, loses 
some of its floppiness and may be read, sandwiched between & pressure pad and the 
read/write head. The rate of revolution is usually 300 r.p.m. within one or two per- 
gent. Presumably it is possible te mount 40 or so heads next to each other, reducing 
head seek time at the expense of disk wear (and cost), but invariably a head seek 
mechanism is used. The outside track (track zero} may be fitted with a light sensor 
and a stop, to give & fixed starting reference point - the stepper motor moving the 
head out until track @ is signalied, then stepping iu, perhaps to the directory track. 
Other sensors may detect Index holes in the diskette and the presence or absence of 
the write-protect tab. The heud has an ‘actuator’ which moves the head In contact 
with the disk when reading/writing, and awny otherwise. The door of the drive also 
moves the head away from the disk, to avoid ‘glitching’ (i.e. magnetic damage} to the 
data near the head on power-on or off. This mechanism also clamps or unclamps the 
disk. Double-sided disk drives hnve two heads, mounted on opposite sides of the disk: 
they huve to be offset sa that each con have a pressure pad. Most microcomputer 
equipment has drives mounted horizontally, or verticslly with front loading. but top 
loading ia used with some desk-atyie equipment. Drives are often palred so backup 
Sopying (from one drive to the other) l4 easy; a whole disk can be duplicated onto 
another, for security purposes, Thle ia not necessary, although it's very convenient. 
Slngle-drive copying can be done by Inading a part of a disk tnta memory, copy lag 
this by awitching disks, re-entering the original disk and reading niore of it, and so 
on. 

Disk drives are controlled by controi clreulta, usualy controller board» which 
Include a apecial disk-controller chip, with functiona to turn the motor on or off, read 
a apecifled aocter of a specified truck, acek a track, and many more, These chips have 
RAM and ROM and perform a Int of error checking, returning Olt patterns indleating 
what (if anything) la amina, The translation of magnetic patteens Into byten Is a herd: 
ware function, relying on aanorted cronsover detuctara, amplifiers, and pulse shapers, 
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Some chips are programmable to return not only bytes on the data bus, but also sync 
marks and address markers and other housekeeping paraphernalia. Commodore have 
preferred to use their own chips to control the drives. Information sheets, supplied 
by disk drive manufacturers, provide interesting information on timing and on expect- 
ed reliability of their products. This is important when writing controlling programs, 
but otherwise can be assumed to be taken account of in the disk operating system. 
For example, the time for the motor to reach a stable running speed is usually about 

t second, and the average time to move to another track about 4 second, depending 
on the number of tracks on a disk; in either case the operating system software ought 
to take these delays into consideration, Other ‘soft’ errors - wrong track found, or 
byte misread, but re-readable ~ should be incorporated in DOS. This is done by 
checking the status indication from the controller, and re-reading data, perhaps by 
moving the head to track zero and retrying. This may be done ten to fifty times be- 
fore the error is considered ‘hard’. The data sheets provided by controller chip 
makers include flowcharts of recommended practice, in the hope of preventing the more 
subtle mistakes. Commodore fell foul of one typical mistake when designing the write- 
Protect software, where the write-gate is kept on when it should be off, 

The diagram shows some of the components of a Commodore drive as it appears 
unscrewed, with the lid propped up. Note the position of DOS ROM chips (most of 
them), and that drive 'zero' is on the right, drive 'one' on the left, with the heat 
sink and printed circuit board above. Drive 1 tends to run hotter than drive 6. 

Both the on/off switch and [EEE connecting 
tabie are at the back of the machine. Units 
vary in smai! details; the 2040 controller 


ation slots. 


/VYoltage controllera/ 


compatible with the 3040. The 3040 and 4040 We bea wink 


models are very similar, with upgradabie _J|RAR chips and contralie 
ROMs available for the 3040. [t is worth lendiie 

noting, with your unit, which way the on/ DOS ROM |c ips 
off rocker switch operates, so that you can L] IEEE} 
check whether it's actually on. Many units sey A 
work like thia: “ 


OFF: 4 on: SY 


But the 4040 haa the opposite arrangement: 


Because of the nature of the JEEE bus. 
several PETa can be connected to the same 
disk unit (and printer too}, but the users 
will have to be careful not to use the disks 
together; if they aren't sure enough to he 
able to guarantce this, commercial products 
of the 'Mu-Pet’ and ‘Regent’ type are avallable. (i suggest that anyone considering the 
Purchase of auch a system shouid first ask the opinion of a current user). CBM disks 
are nct the only storage units around. Compu/think have sold many units; Novapac, | 
bellave, sold fewer; ‘Byte’ magazine of June ‘Bt and fotlowing editiona haa articles on 
controlling diska; Ht. Freeman (Kbaud-Microcomputing, Jan.'80) explained how he added 
§n $-100 disk aystem to an early PET. Other systems continue to arrive on the scene. 

The flnal point | want to make in this section - it ia repeated here and there in 
the next chapter on BASIC disk commands ~ Is that the CAM disk units are largely 
Autonomous and independent of the PET/CBM which controls them. DOS Is held in the 
disk ROM, not in WASIC, So changing the disk ualt, or awapping the ROMa In it, will 
Cniae tt to act differuntly - fur example, to be able to proccss relatlye filus, where 
before it couldn't. The PET/CAM can delye any disk unit; BASIC 2 for example can 
Tun an 8050 or 4040 disk unit, although the BASIC 4 commands havg to ba tranaposed 
“to their more ancestral form. Seo Chapter 6 for examples. 
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Diskettes (‘flo disks') The diagram, which is approximately to scale, shows the 
typical Teatures of a diskette. Bold lines indicate the outline of the envelope and the 
notches and windows in it; thinner lines mark the position of the magnetic surface 
itself. The diskette is square (like the sieeve 
of a record}. it has a write-protect notch; if 
cut out, the disk can be written te; if it is 
not cut out, or if an adhesive tab is stuck 
over it, a disk is write-protected, provided 
the disk drive is designed to sense the notch 
and process the resulting message. Most drives 
have this feature; the idea is to prevent in- 
advertent erasure of important programs or 
data, Two stresa-relieving notches are cut 
near the read-write window, the elongated 
siot along which the read-write head moves. 
The entire disk ig spun within the protective 
envelope; part of it is visible as an annular 
region, which is gripped by the clamp and 
rotated by the spindle motor. The small hole 
neurby enables index markers and sector 
markers to be sensed; the diskette may be 
perforated by one or more small holes, which 
are inside the region used for reading/writing, 
and through which light can be detected. The 
physical orientation of the disk, at least as regards CBM drives, ig as shown, when 
the disk is inserted into the drive. The label side is uppermost, and the read-write 
slot forward. The label is deliberately positioned away from the sensitive recording 
surface; this reduces the chance of fingerprinting, and also enables the diskette to be 
put into its outer dustcover with the label visible and the read-write slot hidden. CBM 
equipment, and much other, uses disks which are 5 1/4" square (the disk surface is 
§ 1/8" in diameter). These represent a fair compromise between the size of the complete 
unlt and quantity of storable data. 

The recording surface is usually a polyethylene derivative, coated on both sides 
with magnetic recording emulsion. Single-sided disks are tested (L'm told) on one side 
onty, or, if the test fails, flipped over and tested on the other. This process also 
tests double-sided disks, which are otherwise similar or identical to those labelled 
'gingle-sided’. When a production run has made its quota of double-sided disks, some 
of the remainder may still be usable aa double-sided disks, in spite of their tabelling. 
The magazines regularly have ‘new! articles explaining how to double your disk capac- 
ity by cutting new index holes and write-protect notches, Bo that the other side of 
each disk is usudie. The standard argument against is that small dirt particles, trapp- 
ed by the self-cleaning wiper lining the diskette, become dislodged and spread across 
the disk surface when the direction of rotation of the disk is reversed in this way. of 
course, double-sicted driven don't have this problem, as the direction of rotation in 
constant. The lining of a diskette depends on its quality, but is often a sllppery 
plastic (e.g. PTFE) woven in a loose texture. like a small-scale atring vest. Small con- 
taminating particles, smoke, dust, and go on, become trapped there and don't interfere 
with the read-write head, or scratch the medium, A track's uscful life is typically 
quoted as 3x05 paases per track. Thta sounds a colossal figure, but in fact, at 300 
revolutions per minute. represents about 7 days! continug! cunning. Diuica containing 
Important data should of course be copied and the master dixks replaced at Intervais- 
It's difficult to make useful remarks on diskette quility: it is Imposnible for anyune 
outalde the minufacluring business to know whether the labels euprosent genuine diff- 
erences, of whether the sane item Is repaeked/ celabelled undfor mixed with other 
butches. The mngtetic properties of retention and sensitivity wlone aru very complex. 
In practice pcopte rely on advertiaiag and on price a4 eriterla. Some brands (Dysan, 
Scotch) advertine their reliability; Vertatim more recently has done the sane thing. 
perhaps In respanne to eritictam; others (IM, RASF, CDC) seem to vely on thelr gen- 
eral ruputation, In any case, # programmer producing systems for anything approach- 
Ing a serloua use must Nave w rigorous peogrim to test dinketion by writing anc read- 
ing to the entire disk surface. 

How ja alf thls actually impiemented on the PET/CHAM's Ryatema? Mich, but not 
alt, ta standard practice. The outer track, unuatty called track zero, and tho inner 
track are arranged aa the dingram shows, with the direvtory held on a gontrel track 
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(or two tracks with the 8050, because of its larger capacity). The directory track(s) 
contain (see 6.4) the directory, with associated pointers and flags, and the block 
allocation map. or BAM. which lists the available sectors for future use, so that new 
data can be stored in unallocated sectors, and scratched data can be redefined as free 
for us¢. The general principle is fairly standard. Apple disks for example have a 
‘volume table of contents’ or VTOC and a ‘track bit map' which have similar functions 
to the directory and HAM. The actual diskette may be either hard-sectored or soft- 
sectored, despite CBM's claim that only soft-sectored disks should be used. The light 
sensing system appears to be absent, so the index marker and sector holes are not 
relevant, (A hard-sectored disk can be identified by careful manual rotation of the disk 
in its envelope; if there is one hole only, the disk is soft-sectored; if there are many, 
for example eight, the disk is hard sectored, Hard sectors rely on light sensing to 
position and read individual sectors; soft sectoring uses software). We shall see in 6.5 
how to program CBM drives to read or write to any track, and to any sector within 
that track. But first let's consider the rationale behind sectoring tracks. 

_. The point is that small variations in the spindle motor speed cause data being 
written at a constant rate to vary in its physical length. Sectors are separated by 
gaps, and these gaps allow for speed differences between machines; a slower machine 
writes longer sectors, and vice versa. {There is a curious passage in Osborne- 
Donahue on this subject). Sectors usuaily hold 256 or 512 bytes of duta; there may be 
from about § to about 30 sectors per track, depending on the recording method. For 
example, double and quad density recording stores respectively twice and four times 
the normal amount of dota, by doubling the number of sectors or doubling each sect- 
or's contents or both. {The number of tracks varies too, of course). A diskette's 
total storage capacity is tracks x sectors per track x bytes per sector ... usually. 
Commodore uses an unorthodox and ruther horrendous system in which the number of 
Sectors increases as a track is further from the centre. This allows about 203% more 
data to be stored than would otherwise be available with their single-sided, single- 
density systems (double-density with the 8050). It means that the rote at which data 
is written is faster ut the edge of the disk than the centre. Usually the rate is fixed, 
30 all sectors occupy the same angular distance. Commodore's technique takes advant- 
age of the fact that greater resolution is possible at the edge of a disk, (For the sume 
reason, records reproduce sound better at the start than the end, and have large 
labels in the middle), 

The diagram that follows Ulustrates the way in which data is stored on these 
disks, It is recovered by a decoding process, and synchronisation fields and clock 
Pulses are detected by their bit patterns, which are not data bit patterns, Much of 
the reading and checking is on time, and not on counting. The 'cyclic redundancy 
check’ Is a form of hashtotal which follows the data, it [s read from the disk only 


a ONE SECTOR OF A TRACK - - - - - - - - ee 
Sync. |/1.D.¢e.g (CRC | Gap | Sync. jAddresa|256 bytes af date CRC| Gap 
Field|4 hytes) Field|Marker |CBM includes pointers 


efter the 256 bytes or so of duta are in thelr RAM buffer. Incomplete use of the error 
detecting software here, and in many other cases, may permlt spurious data to enter 
the syatem. 

Soft errors may be caured by physical contaminants, and dy clectrical noise, 
Statle etectricity, defects In the disk surface, npeed variations and 90 on; these are 
curable by repeat re-reading of the disk, Hard errors can be minimised by care of the 
note and atso by careful dackup procedures. The error-checking mechanisms, if 
ey are ured, are pretty formidsbie, and correctly-adfuated hardware with well-des- 
Knod software should be extremely reliable, Hare error rites of 1 bit In 10%) give an 
iden of the cellabliity attuinable; this figure ja quoted ina disk drive's specification 
sheet. Sevetian 6.9 of this chapter aummarisen the care and maintenance which it 1s 
prudent to apply to drives and diskettes, However, it ls worth remembering that the 
reaaity of daia transfer between a computer und diska Ia nowhere near that of dota 
7 ‘insfor within RAM asd ROM, where xevural hours’ running time may reach this 
figure cioll pits transferred). : 
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6.2 Software 


What is a file? This concept is quite difficult to grasp; only with practice and exper- 
ience does it appear a self-evident and obvious idea. Data when stored in some device 
external to the computer (tope, disk, another computer, etc) has to be arranged in 
some sort of logical way, te be accessible again; any collection of accessible data may 
be eatled a file, The operating system usually enables files to be named, so that they 
are easily identifiable, and adds housekeeping features to the data which, by standerd- 
ising the input and output routines, allow the use of relatively eesy commands, like 
INPUT$ and PRINT#. Housckeeping with CBM disks includes such features a5 the 
special treatment of (Return] as a record separator, the special treatment of the comma 
and colon as ‘field' sepurators, and the automatic generation of header or directory 
records in which the file's name, type, starting address or buffer position are stored 
for later recovery. When the file is read back, this information is used to process it 
correctly. For example. programs and data are held ruther similarly, as bytes in 
blocks on tape or disk, but a program has a different value in one of its header bytes 
which causes the operating system to carry out the load routine into RAM, rather than 
prepare a data buifer for reading, which is what happens with a file. At first sight, 
this seems extremely involved, but with practice and thought it soon becomes fairly 
easy to guess what parameters wil} be needed to make a file system operable. Large 
computers use a variety of file organisations, many af them unavailable on smail mach- 
ines. (In fact, people who have worked for years with mainframes or large minicomp- 
uters are often unable to understand the difficulties of working with tha more restrict- 
ed operating systems of microcomputers}. The summary that follows describes these 
file organisation methods, All of them can be implemented with CAM machines in prin- 
ciple, but learners will be well advised to use only those systems that are supplied 

by Commodore, or which are available as extras with the use of other manufacturers’ 
firmware. The names of the methods aren't standard, so I've referred to CBM file 
types in block lettering in the hope of reducing confusion. 


Sequential files. These files are one of the simplest types in ¢oncept. The only file 
construction which is simpler is (i suppose) simply a file containing consecutive bytes 
of data with no special characters, a long list of data with a method to indicate where 
it ends, Most microcomputers, apart from the very cheapest with no file-handling at 
ali, implement this system. !t is very suitable for tape storage, because tape reading 
and writing iy almost invariably linear because of the difficulty of winding tape at high 
speed to read differcnt records. It is also suitable for records of vurtable length, be- 
cause there is no need, as there is with some other mothods, to ensure that ail the 
records are the same length, CBM, and moat other micros, uxe the system in which 
the (Return] character octs as a record separator, A ‘record’ may be made up of 
‘fields'; the record is a complete entity, perhups name, address, and severai other 
detaila, in which case there is a ‘field’ corresponding to name, address, and so on. 
In practice each record !s usually designed with the same number of fields to euch 
record, so that every recurd can be read in the same way. COBOL is particularly 
well-adapted to explicit handling of fleldy and records and file definitiona Ilke thia one 
appear at the start of all COBOL programs: 


Ol «= LOGFILE-HEADER. 


03 DOCUMENT-NUMBER PIC 94). 
03 = VDU~NUMHER Pic oO. 
03) | -YOU-RETURN PIC 9{4). 
03 ‘TRANS~STATUS PIC 89(4}, 
0300 TRANSACTION. 
O35 TX-NAME PIC X(t}, 
OS TX-Ib Pic X¢2). 


This means that the record catled 'LOGFILE-HFADER' Is 27 bytes long. mode up of the 
flelda named a9 shove, und with the format specified, where % menns a numeral, 3 8 

sign, and A an aiphanumeric character, (This autetion his been used In Cis printer 
with Uttle change), HASIC haa carried over fram FORTRAN the habit of not defining 
files at all rivorousty. Rather than une the fermatied Inyout of the type above, HASIC 
soparates records by [Heturn) and flelda, where the distinction [# kept, with comes 
or cotons, This in becnuse PRINT # always senda a [Heturn} at the end of tia current 





| 
| 
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output string. This is sent to the tape or disk, and stored there, so it may as well be 
put to use as a separator. Similarity, INPUT# is designed to take in a set of characters 
up to the next Return], If this set of characters includes one or more commas or 
colons, an input statement of the form INPUT#, X$,¥Y$,Z$ will assign XS, Y$ and so 
on to fields within the record. All this is quite straightforward (when you've grasped 
the ideat) and section 6.3 has demonstration programs. There is one complication 
peculiar to Commodore: PRINT and PRINT# each follow [Return] with linefeed (this is 
ASCII character 10 decimal), originally so that the next line on the screen would be 
moved to, whenever Return was pressed. This character is filtered out of cassette tape 
files but, with BASIC<4, left to print to disk, To get rid of it a construction like 
PRINT#S ,X$;CHR9(13); or PRINT#B, SCRS; 

had to be used. BASIC 4 has a patch in its print routine which deletes this character 
if the file number is less than 128. For chapter and verse, ace PRINT and PRINT@# in 
Chapter 5. ‘ 

The diagrams which follow are an attempt to explain the layout of sequential files. 
I have used [R] ta mean Return, which is #0D (13 decimal). The first shows a file of 
this type in which only records have been written (i.e. there are no subdividing fields 


Within a r rd). 
ened) Lrbaria 4 44n2222 22232 222333 3 
byte: 1234 5 678909 12345 6 789012 3 456 7 99012 3 


File: [3]O[#]¥](R1[S[¥] 1] T]HPIRI[ AL] A] N]ERI[CIATR] TI] R[ CRITE] [el iR) [BAT RPO[NT IAD 


{n this case, a program to read the file will have input statements of the following type 
within it at some stage:- 

100 INPUT CNS: [NPUT SNS 

200 PRINT “FULL NAME IS "; CN$; " "; SNY : 
This format 1s obviously dictated by the structure of the file, where Christian names and 
surnames atternate. The second example shows a file where separate fields have been 
used, a technique which calls for the use of statements like PRINT#,[$ "," NS "."M:- 

t—— Record #1 ———>» 9 —— Record # 2 ——-_——> Reed we 3 


rine:(cf |, [a] al1]s]«].[5}5[tai[o].r].[,[alejofato 7 ]2[ 5] @[ces]ul. [Ts] R[o[o] y [7] 


Here, because of the separators, we have the option of using either of the foilowing 
types of input statement to read the data from the file. Note that again the file is 
written in a regular way, with equa! numbers of fields in a record, so that any record 
May be processed in the same way as all the other records. This is not necessary, but 
it does simplify programming. Alternative techniquea include the use of a number in the 
first field which counts the total number of fields in that record. 


100 INPUT £$, SN$, M : PRINT “NAME, SCORE = ” [$ SN3 if 
or 100 INPUT I$: INPUT SN: INPUT i 


CBM equipment ls designed so that PRINT and PRINTY# send to tape or disk the same 
cheracters as they would have sent to the screen, so that if PRINT and INPUT match 
there should be no problem, The last example, where two strings are followed by a 
number, Ulustrates this. As long as 1$, N$ and M are written to the fite, they can be 
read back by the samo veriables. There la a passage tn Osborne-Donahue (p.300 app- 
'x.) which seems to suggest, erroneously, that there ls aome difference between 
umber and atrings in this respect. 








Relative fites. These ure gometimes called ‘random access’ files. Each record |s the 
same length; any record can be calied by number, without, an with a sequential file, 
having to wilt while the entire file ia rend from the start. The orgerniantion of the 
Fecords ts Identicn! to that for sequontial files, except that each record ja the anme 
lenyth, op at lenst not longer than the predefined length of a full record. (Some may 
Ne “xeepllanaly shert, but as long aa the number of fields Is correct, an esrty [Ret- 
Wnt charecter will not disturb the file). However, in additlon ta thia file, there must 
fine be a subsidivry file which enables the positlon of any record to be compuled, CAM 
‘qulpment with DOS 2+ uses a chain of axo-called ‘aide-aectors' for this purpose. DUS 
‘hoa 9 very long program to achieve ihe same effect with "User Clea’. The algerithm 
which determines: the data position may in faet be external: uxing the sector writing 
ay of many dlak drives makes possible the conatruction of files in which the 
4A. record in Kimpsy the nth, sector of the dink, Record number @ might be teack 0, 
lor 0; record 1 in svetor tof track 0; record 2 In sector 2 of track 0; and ae on, 
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Direct Access Files. This file access system, like the last, is sometimes called random 
access, Secause a file on the disk can be read or written ‘ut random’. It is a version 
of relative access in which records are not called by number, but by some key. This 
key is encoded, converting it into a record number, and the resulting record read. 
To clarify this, suppose we have the facility to write relative files (e.g. via DOS 2+), 
but we wish to be able to retrieve records using telephone numbers (or names, or part 
numbers ...) a8 the key. One method might be as follows: store in RAM a table of 
each phone number, in order. Then when an enquiry is to be made, this table could 
be searched, using perhaps o binary chop search, to convert the phone number into 
a number within the range of record numbers on file. This would be quite fast. The 
drawback is that new records could only be inserted into the file by rewriting all the 
file above the new record, moving it up one place. An alternative approach, direct 
access codes the key using a ‘randomising algorithm', positioning the record according 
to the resulting value. Records are held in a completely jumbled sequence, but the 
point is that the algorithm enables any of them to be quickly located from the key, 
without any disk overhead. A file of this type must be larger than the anticipated 
number of records; at least 303 more space must be provided so that new records can 
be placed without too much difficulty. Suppose we open a direct access file with space 
for 1500 records of fength 50 each, antictpating about 1000 records in the complete 
file. We devise an algorithm which converts any telephone number into an integer in 
the range 1-140G, (The extra 100 allows for ‘consecutive spill' forward). A good algo- 
rithm will spread the resulting numbers evenly. We may be able to improve on this 
using known facts about distribution of such numbers; if for example the final digits 
ave evenly spread, 1400/9 * final digit will ensure that ten equal chunks of date are 
produced by the algorithm. Another expression evaluating to 0-150 or so must be 
added to give the randomising furmula. Other methods include: taking the remainder 
after division by a prime number; using RND(key) after RND(-1) to generate repeat- 
able random decimals from G-1; splitting the key into parts and adding, 

The outcome of this will be the sort of situation shown in the diagram. Three 
telephone numbers have been processed by our algorithm, and yielded the values 
shown. The records are therefore written into the file: 

765-4921 bocomes 752; 741-0123 becomes 53; 300-3000 becomes 297: 

on —— 


—> 
rut: OB errr 


Now, when we wish to read the record corresponding to 765-4321, we perform the same 
encoding process, and read record 53, What happens if an algorithm generates syn- 
onyms (strictly, the original keys are ‘synonyms'). We store it further up the file, as 
near ay possible to its originally computed position, This implies that each record must 
store its key as well as the associated data, or have some other means of distinguish- 
ing a ‘home key’ from a ‘synonym'. 

If all the records are stored in the file as they are processed, and the algorithm 
la truly ‘random’, the proportion of synonyms expected is half the packing density. in 
our example, 1000 of 1400 records, about 71%, will be utilised. So about 35% of keys 
will bo synonyms. !f synonyms arun't entered immediately, but are stored in another 
file for later entry, the proportion of synonyma drops by about 25%. So, in this case, 
sbout 25% of keys will be synonyms: but the number of records which need to be read 
when a vynonymous record is read Is higher. 

This Js a fuscinating system on which to organise files, and ls quite an easy one 
to implement. [t hus the serloua drawback of making 4 sortud sequential read of the 
fife diffleult, because of the randomised order. To du thia, another file, folding ail the 
koyn to date, ia required. This will nred to be sorted or merges at Intervala, Then it 
cin bo read acquentlaily. and the corresponding records calculated and read. Another 
drawbuck ja the wasted space, a necessary concomitant uf the technique. 

To summarise: if this louk-up method appeais la you, Follow these atepa: 

(1) Declde whether it will, In fact, do what you want. 

J) Experiment with ‘randomining' tecttques, taking account of regularities la the 
kwy field, Find one with » goud apresd, 

Cid) Minko an estimate of the optimum File size. 

(iv) Enter the most frequently used records firat; many will bovome ‘home! records, 
funter to rotricva and rewrite. . 

(¥) Don't write aynenyms untll the second pags, to maximise the number of ‘home’ 
records which the (is will cantaln. 
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Indexed sequential fies. IS or [SAM files are one of the most popular types of file in 
commercial use. They are unobtainable on most microcomputers as standards, although 


some firnnware (e.g. EPROMs) has been produced and advertised with this type of 
feature on it. These files are readable sequentially in sarted order - for example by name 
or by customer number, but in any event by a range of possible keys. Any individual 
record is also rendable or writeable at will. This can be accomplished only with sub- 
sidiary files, hoiding keys ond pointers to their records. Any new record necds to be 
merged and sorted inte this index, perhaps on five to ten different keys. A self-main- 
taining system of this kind isnot easy to write. Some small computers - the [BM 5100 
series, and ‘Microstar’ ~ do have this facility or something like it. 

The example which follows is a smail-scale version of the reali thing, but shows 
the generat principle. I've assumed a rather short file is set up, which is accessed by 
a single key, expressed as two letters. The index file, which has the same number of 
records, stores each key used so far, together with a pointer. Now, when the file is 
to be read in sequence, this index file is read first: record AA is to be found in the 
main fie ag record 1, then record AB as record 2, and so on. If @ record is to be 
read at random, say DG, the index is searched, perhaps by a binary chop. since it's 
in sequence, and when DG is found, its pointer is read and the corresponding main 
file record read. This of course ig slower than any non-indexed method which reads 
its main record directly. Relative records for example are faster to read, but can only 
be regarded as ‘indexed’ if for example a client number equals his record aumber. 


Record #1 Record #2 Record #3 Record #4 
WAIN PILE: [AA detail | AB detail | DG detatt [QR detail] 
INDEX ViLR: {AATJAB2]DG31 Qa) 








Suppose two new records, ZZ detail and FF detail are to be entered into the indexed 
sequential system. Firat, we append the new records onto the main file as it exists at 
present. This expands the main flle like this: 


Record a Record #2 Record #3 Record #4 Record #5 Record #6 
MAIN FILE: [aa detail AS detail [ DG detail Tar detail [ ZZ detail | FF derail } 








The index file needs two records added to it, viz. Z25 and FF6. These, however, 
cannot simply be appended to the index file, since then the sequence of records is no 
longer maintained. Instead, they are sorted, and merged into the index file. (The sort- 
Merge is 4 universal technique for incorporating new data into an already sorted file: 
after sorting, each record is compared with the file records until a position is found 
into which it fita the correct order}. The resulting index file is: 


Iwpex Fite; [AA |A02[ 063] Fr6/qRa} Zz5| 


This, of course, Js only an outline of one method of many by which this system can 
be put into operation. 


Inverted flles, This file organisation method [s used In data-base procesaing, whera a 
file of data is rend and the entire file ls potentially a source of information; the data 
base is interrognted using keys. which typically may be combined using AND, OR, NOT 
and other Boulean operators, The object is not to rend an entire Fille, checking on each 
Bingle record, but Insteud to cut down the number of possible records aa rapidly as 
Possible. This means the construction of a number of key files. Every new record 1s 
entered In the main fle, and ita record numbar hea to be appended, or preferably 
Merged, Inte ench key file for which its detaila ure relevant, This process ie Ilkely ta 
4 quite alow, but increased efficiency subsequently may make it worthwhile. The 
*anmple, 1 hepe, spuaks for itself. 


MAIN PILE: Record # fi 3 (s3a709 10 11 22 13 14 25 16 17 16 19 30 21 2a 33g 
PRice nancx 1: [1 69 4 15 16 29 22:93 5450... 
PRICK RANGH 2: [48 712 09 17 (4 24 Wd 27 265.7" 
PRICE mANOR 3: [6 0 49 11 14:15 10 4) 2S 2H JUL,, 
ARIA 1 : [6.4 10 1 1415 16 a4 28 ae |g, 

AKA a : [9478012 26 21 22 23 94 TF 
ARRA 3 : ; 
COMA TYPR A: 
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Direct track-and-sector access methods. Many very efficient systems for the use of 
disk data are hybrid systems in which data is loaded into a buffer and processed 
there. An entire track of data may be toaded into memory and senrched while in RAM, 
for example, A sector may correspond to several records, which can be poked into the 
sector and written back to disk. Searches for Boolean matches can be carried out with 
machine-code routines on data in RAM, It is possible to save the entire set of BASIC 
variables on disk and reload them later: when used with integer arrays this can be @ 
very powerful method for storing a great deal of arithmetic information in RAM, where 
recall is fast. 





‘Opening’ and 'closing' files The following statements are taken from a variety of 
computers. They all open ane file. Through the idiosyncrasies of syntax 8 few prin- 
elples underlying this process may, 1 hope, shine through:-~ 


OPEN FILE FL2,'040',3, *RASTIND’, IN, KEY 

OPEN 1,1,1, "TAPE SEQ. RECORDS" 

PRINT D$"OPEN WAIL LIST,L200,D0" 

BELECT LOGFILE ASSIGN TO EDS ACCESS 1S SEQUENTIAL 
DOPEN#G, “REL DATAFILS",D2, 


All these include; 

() Some future reference for the file ~ a name or number. 

(ii) Request to use the file for writing, or reeding, or both. 

(iii) Reference to the device or drive to be used, unless this is implicitly given. 

(iv) Description of the type of file, at least if the file is a new one. . 

(v) Some internal system to assign a buffer for storage of data, which has been read 
from the device but is currently stored awaiting processing; or which is to be used 
to store data before it is written to disk; or both, 

(vi) An impticit requirement that the file be closed at some future time, whereupon the 
final buffer of a write file can be processed, and the directory or header details 
of the file updated. 


6.3 Commodore disk drives and file handling 


The 2040, 3040, S040 and 8050 drives At the time of writing, these drives are the 
most widely available CBM drives. The 8060, using 9 inch flappy disks and 1BM format, 
and a winchester unit with a singte drive, have been announced, but are not widely 
available, A single, shoe-box sized drive for the VIC, called the 4020, also exists. 
(Note: CBM's disk units are assigned numbers ending with 0, except the 8061 and 8062 
where single and double sided disks sre distinguished. The -0 suffix contrasts with 
the CBM machines. where -08, -16, or -J2 records the RAM inatulled at the time the 
computer is sold. Most printerca end with -2. Clear? [t all started with 2001...) 

The four drives are similar in appearance.* The 2040-4040 sequence represents 
continued improvement within the limitations impoxed by single-sided, aingle-denalty 
5 1/4 Inch disks. Several physical changes nave been introduced: the 2040, of which 
there are &® number still around, was notoriously prone to heating and other problems. 
{t is not particularly easy to upgrade, as its internat main printed circuit bourd has to 
be changed. The 3040 avoided some of the problems of its ancestor, while retaining 
others: for example the diskette clamp scems to lack the normal precision centring 
mechanism, Bo that it in widely recommended to closy the disk drive door only when the 
disk {s revolving. (nitlslinatlon of the disk (nee [NITIALISE ln Chapter 7) is still ob- 
Hgatory It thia model. Finally, the 3040 une DOS 1.2, which, while an improvement 
on DOS 1 in its error-trapping, still unly provided sequential Silest All these objections 
were remaved by DOS z.1 and the 4040 drives, The romaining diffieuities arg sumer 
lsed In section 6.8 at the end of thla chapter, The $030 has more than twien as many 
tracks, und about 40% mor: sectors, on the samo sizo disk. The diskettes therefore are 
entirely non-Inturchangnabla. The dink duorn and disk retaining mechanlam are differ: 
ent, presumably better, and the central warning LED signals green ang red > not just 
red! No doubt there are production fing changes of a highly technical type which are 
not widely known, This then is the evolutionary history of CHM's disk drives to date. 





nr 
*The steel casings are aade by Canada’s targest barbeque~equipsant factory. ff thera 
im ey aysbolle significance in thin I've been unsbie to find it. 
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The drives were issued contemporaneously with the 2000, 3000, 4000, and 
: , a $000 mod 

hel Aectigieiphrteaes respectively, and ere therefore often seen together, because they ae 
prod Aan Hs “er As mentioned before, the capabilities of the disk drive lie within the 
am it itself, so it is more important to select the correct disk unit - or to be prec- 

e correct ROMs - than the appropriate version of BASIC. The single most import- 
ant feature of a system is the storacle amount of data; if a user wants a program +6 
access 2 million bytes, obviously the programmer will be in trouble with a smail capacity 
disk pit pvp atthe data-packing techniques are used. 

ow cam the different drives be distinguished? The obvious way is t 

Commodore ae on them, if they aren't obscured by dealers' logos, ut ib a see 
ph a ieble, because of the possibility of updating the ROM sets in the 1040 and 
Mg rare ae example, 4 3040 unit may have been upgraded from DOS 1.2 to DOS 
e. " te allible way is to peek the disk ROMs themselves; a location which has 
ne reas power of discriminating between disk ROMs is $FFFF in the [RQ vector. 


OPEN 13,8,15: PRINT#i5,"M-R" CHR$(255}CHR$(255): GET : 
« > #15,X$: CLOSE 1%: 


Prints the decimal value of this location, which = i i 
; S| . = 213 with 4040 drives, and 242 with 
8050 drives. At the time of writing, there are at least two DOSs for the 8050; theae 


can be identified b M ; 
the newer DOS a CHR$(195)CHR$(251), which returns 32 with DOS 2.5 and 170 with 


And thig table summarises the main characteristics of CBM drives: 


2%176 G4O 2x17! $20 





2x176 540) 2x171 520 


2xt74 708 2n169 728 


2x533 298 2” 518 400 


°A very long demonstration 
; program may be used to construct files like these: 
pond direct-access techniques may be used, Neither comes with DOS. Se ae 
hip centile eee : the disk doorn aren't closed while the disk is spinning, to 
ralige the disk, the directory may not read, and you wii! h ir 
The mensage 20,READ ERROR. 17.0 is typical. Ss Med 
ene ia is the oldest and least reliabie. 
en (sa 4040 i i % i 
ait silent ds q writes to a disk formatted by DOS 1.2, an error message like this 
73,C8M DOS,19,97 
ue the disk will become unreadable. The same thing happens if DOS 1 weites to DOS2, 
prvi techniques are known (e.g. ilarry Beoomhall has programs culled ‘Lazarus') 
ert they are hazardous and success cunnot be gunranteed. Therefore, take care not to 
‘i ie with DOS 2+ onto DOS t¢ disks, or vice versa. Sometimes this happens out of the 
ane i, cum ard dink Wad 4 es Ramo, which only appears if a score on one 
oe yume exceeds a cerivis valuu. To cause thia to happet, the dire q 
on the disk, possibly damaging it. a eae 
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CBM file types: Sequential, ram, relative, and user A directory or catalog of any 
CEM diskette (sce Chapter 7, CATALOG) fists files on disk with a three-letter code to 
indicate the file type. The possible codes are SEQ, PRG, REL, and USR, Occasionally 
DEL (deleted) makes an appearance, and sometimes *EL or other anomalous code, These 
latter are connected with the problems of scratching unciosed files which xre discussed 
eisewhere, and with ugs in the COPY command as applied to retative files. Apart from 
malfunctions of this sort, tha four file types (or three in DOS 1, which has no REL 
files) are recorded in the directory at the time the file is written,es a Nag: if the flag 
is #$00, a scratched file is (or was) present; if it is #581, #$62, #883, or #384, the 
directory translates the value into SEQ, PRG, USR or REL respectively. A file opened 
as a sequential file listson the directory with SEQ; a BASIC program saved to disk 
lists with PRG, not surprisingly. Machine-code also lists with PRG, so there is no way 
to tell from the directory whether a PRG is BASIC or machine-code. Saving with names 
like ‘OLD.033A' is the usually recommended practice for the meticulous programmer. 

As we'll see, program files can be opened for reading and writing as though they were 
sequential. This is uscful in the compilation of certain types of utilities for programs. 
such as cross-referencers for variables. 

User files (USR) are. so far us I'm aware, identical to sequential files. Their 
sole purpose seems to be to give the impression that the subsidiary files which are 
opened by the relative file demonstration program in DOS 1, are notably different from 
the main data [ile,and from other sequential files on the disk. 

Section 6.4 of this chapter explains how each file type is stored on the disk. It 
is not necessary for comparative beginners at programming to understand minutiae of 
this sert, and the remainder of this section explains file-handling from BASIC. 





Files and BASIC: (i) Formatting new diskettes A box ef diskettes which haven't yet 
been used ought to be dealt with in a standard way, so the status of any diskette is 
fairly self-evident. CBM disks may be formatted with a two-character i.d. it is a yood 
idea, in principle, to ensure that each disk has a different i.d., 4o there will be no 
chance of DOS garbaging the data on a disk by confusing it with another of identical 
i.d. This will only be possible with backup disks. Typically, the iabels supplied by 
the disks' manufacturers wili be stuck to the disks and filled in {with a felt-tip pen!}. 
The process of writing a name onto a blank disk, and recording i.d. markers on all 
its tracks and sectors, is usually called ‘formatting’. Without it, a diskette cannot be 
written to or read from. The pattern is characteristic of a particular disk unit; most 
disk drives can't read disks written by other brands of machine, because the number 
and position of the tracks and sectors is not the same. When carried out on a diskette 
which holds data, the rewriting process can be considered to erase all the previous 
Informativn, 30 it is rather important to take care with it. Juat to be confusing, this 
1a often called ‘initinlising’, the name CHM use to refer to the process of reading a 
disk's directory and BAM into memory, a non-destructive operation. If you switch from 
one computer to another, it may be necessary to remember thig fact; ‘initinlise' may 
delete alt your data if tried on another machine. Conversely, in CBM BASIC, HEADER 
or the non-HASIC 4 command Disk NEW, format disks, These are discussed In Chapter 
7 wnder HEADER, but here ore four examples of the commands. 

The two first exampies have the effect of formatting an entire disk, giving it 
the name DiSK RW and the i.d, V6. HEADER can only de used by BASIC 4-nurller 
BASICs don't recognise the word. But Dink NEW can he cun with any BASIC. 


HEADEK DF, 1V6,"D1SK an’ ‘REM DISK ASSUMED 10 BE IN DRIVE 9 
OPEN 25,4,15; PRINT#15, "NEWO: DISK Rw, ¥6" 


The noxt examples retain the previous l.d. and sinply reformat the directory. This 
does nat format the entire disk. 


HEADER D7, "DISK RW" HEM DOESN'T FORMAT THE WHOLE DISKETTE 
OPEN 15,8,16: PHINT#15,"NQ9:DISK Rw" 





Fites and BASIC: (ti) Channef 15, the ‘error’ channel Channel 15- secandary address 
TS in on OPEN statement - la specially reserved fur uae by IEEE equipment, of which 
CAM disk deives arc an Important example, Ita function is to aet ag a buffer for DS 
an DS$ messages about the dink stetua, (See Chapter 7 on DS and S$ for mare on 
these reserved varintles). Moat of these mesanges aren't really ‘errors’, but ihe name 
laa convenient one te use, alsa anubles cemunirds to be transferred from HASIC, 
auch an PRINT#OLS, "NEWO:OISK KW", an wo've just acon. WH DASICa before BASIC 4 
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programmers had no option but to get in the habit of opening this channel and print- 
ing to it or reading messages from it; BASIC 4 has automated this process, so that it 
needs to be done only at the start of a session. Chapter 7 lists all the DASIC 4 comm- 
ands which perform diak file operations, along with their channel 15 equivalents, all 
of which, incidentally, work in BASIC 4 too, so that it is possible to write disk-file 
handling programs which will run on any version of CBM BASIC, When reading Chap- 
ter 7, remember that the statement OPEN 15.8,15 is assumed to have been executed, 
to open file 15 to the error channel, Other file numbers are often used in the literat- 
re, for example OPEN 1.8.15 which is followed by PRINT#HL or INPUT#1. ft makes no 
difference, except that consistency is helpful, and 15 is mnemonically good. 


code, with a BASIC loader, Its fill title is ‘Universal DOS Support’ but this is too long 
for the disk directory, so it appears instead as ‘Universal Wedge'. Its purpose is to 
extend BASIC's direct mode to include several disk handling commands. These inciude 
initialisation, sending a directory directly to the screen {leaving BASIC intact), and 
loading disk programa. BASIC 4 needs this program far less than BASIC<4, because 
many of its commands already handle PRINT#15 automatically. Chapter 7 notes when 
DOS Support is useful. for example when reading a directory with BASIC<4. The 
symbols @,>,7, and\are intercepted by DOS Support from BASIC. Since some of them 
are also valid in BASIC expressions, DOS Support has an elaborate built-in routine to 
enaure that direct-mode commands are accepted, but program-mode is rejected. (Otd 
versions may have this test missing). Although I haven't repeatec a comment on DOS 
Support in every command in Chapter 7. every command listed there of the form 
PRINT #15,"..." may be simplified with DOS support, in direct mode. For example. 


@Ng: DISK AW, V6 
formats a new disk with the name 'DISK RW’ and i.d. V6‘. 


DUM is a BASIC program by R Leon of Prominico Ltd., Vancouver, which carries 
out disk maintenance for people who haven't puzzled out the operation of CBM disks, 
or who like a program to run things, This again was more necessary with BASIC<4 
than it now is with BASIC 4, which has casier commands. Nevertheless this utility, or 
others like it, remains valuable bevause of the effortiessness it brings to disk handling. 
It operates in direct mode only, and is not a fite-handling utility. instead, it prompts 
the user, with a menu, to choose options like 'Copy', ‘Backup’, and 'New', which carry 
out these operations only after asking the operator to check that the relevant diska 
are correctly in place. This, of course, reduces the chances of a blunder. The pro- 
gram includes a special feature, a ‘history file’, which is a sequential file called "DISK 
DATA‘ or something similiar, and which stores several dates, for example the date of 
the last backup. and comments. 'Filemaster', by L Sasso, is a newer disk utility. 


Files and BASIC: (iv) PRINT# and INPUT# and GET# These BASIC commands send 
output to a file and read it back, either ag u batch or characters (ENPUT#) or as 
individual characters (GET#}. We shall see in the specimen programs how these comm- 
ands operate with ench type of file, Meanwhile, in outline, the importunt features of 
them are as foliows (more detail ia given In Chapter 5 about each of these BASIC key- 
words}. 
PRINT# outputs strings, variables, expressions and literals to the file In the 
same way that the output is sent to the sereen, For exampic, PRINT #8, 
"HELLO"; X; Y¥$; 23*34 sends HELLO, the current value of X, the string 
Y¥$, and the number 57 to the sume line of the screen. However, it also 
sends a eurciage coturn + line feed at the end of the line, which In why 
the cursor {4 now positioned at the beginning of the next Ine. This is the 
major tricky point about PRINT#. BASIC 4 contuing a patch which avotds 
nending a Unefeed character if the fe number Is < (24. If the fle aumber 
jn 12H or more, HASIC 4 behuves Uke HASIC <4, anid the resulting records 
on file wil begin with Unefeed ehseacters, ‘This in not a disaster; if means 
only that the records will mysteriousgly print one ling below Chele expected 
place, and will be one charactor longer than expected. The cure la ta use 


PRINT#A, “HELLO": X; 49, 23934; CHRI(13), 
or PRISTOS HELLO" VG E9094 CRS | REM WHEAL CAS=CHRO(13) 





when uxing WASICS4, The snma trick may alse be used with HASIC 4. 


~ 
~ 
“Seer nace ne Feith cranes faded. onsale chelate eect tademebnene endettern de enna timmneitiinentetel Sree voatic ene 





Programming the PET/CBM ~170- 6: Disk drives 


INPUT # behaves in a very similar way to the screen input statement. It is a 
simple command to use, provided only that the programmer remembers to 
match the format of PRINT# with that of INPUT#. Often, of course, this 
happens automatically, because a programmer will naturully tend to use 
identical variable names when writing te a file with PRINT#, as when read- 
ing back the same data. ] have explained this before in section 6.2, with 
reference to sequential! files; it is also explained in Chapter 5 under [NPUT 
and INPUT#, For those new to programming. the point to understand is 
that PRINT# and INPUT# are mirror-image commands - what one of them 
writes, the other will read. Generally, it is not necessary to know about 
the speclal characters which make this possible, beyond being careful with, 
er avoiding altogether, the use of commas and colons. 


GET# reads individual characters frum a file, including ali the special characters 
like quote marks (ASCI! 34), carriage returns (ASCII 13), linefeed char~ 
acters (ASCII 10), plus all the punctuation symbols and screen editing 
characters which CBM machines have at their disposal. This makes it far 
more versatile than INPUT#, if you are interested in the complete contents 
of a file. If you're not, the ‘intelligence’ of INPUT#, which assigns var- 
jables for you, is a detter command, 


Files and BASIC: (v} The status variables ST, DS and DS$ This last subsection of 
our summarising trot provides a brief revision (or prevision) of the functions of the 
status varigble ST and the disk status variables, given the names, in BASIC 4, of DS 
and DS$. The method of operation of ST is outlined in Chapter 5 under the heading 
ST. (Strictly, it's not a reserved word, but that chapter seemed the best place for it). 
BS and DSS are described in Chapter 7; they are not, strictly speaking, reserved 
words either. What is the purpose of these variables? The difference is quite subtle. 
ST is coneerned with input/output processing from the PET/CBM's point of view, so 
if a device isn't there, or doesn't respond correctly, ST becomes changed from its 
initial! value of zero to 1,2,.4,8,16, ... depending on the error condition. Thus, eight 
different conditions at most can be signalled by ST. The most used in practice is 
probably the end-of-file condition. ST = 64 signals that the computer has not received 
a byte from the peripheral, sc the end-of-file flag In ST is set, on the theory that the 
programmer will check this and do something about It. It is always possible to write 
one's own end-of-file markers. in commercial computing, terminal records contsining 
say ****T are used. When this record is read, the file is closed without attempting to 
read further. However, because of the possibility that a file isn't correctly closed, in 
which case the marker will be absent, the use of ST ia still useful, particularly with 
other peoples’ flies, 

DS and DS$ are generated internally by the disk DOS, and are only available to 
the computer when gpeciaily read. In BASIC 4 this is easy: commands of this type 


10 INPUT#S,X$: IF DA>19 GOTO S000: Alt SO0GO PRINTS 2RROR MESSAGE, AWAITS ACTION 
or 100 INPUT#S,X$: -PRINT DS$: REM CHECK YTILITY BY PRINTING DISK STATUS EACH TIME 


mean that the statua of the disk unit after performing !ts operation can be readily 
checked, Note that DS, the error number, which equals the first numeral in DS$, can 
equal 0-19 without being counted as an ‘error’ - see the table under DS$. BASIC<4 ie 
more trouble; in program mode, a subroutine of thie sort must be used: 


10000 OPEN 15,868,135: INPUT#15,X: IF 4°20 THEN CLOSE 15: RETURN 
10010 INPUT#LS, ¥,ER$,2: PRINT X"," ¥ "," ERS "|" Z 
10020 PAINT “DISK ERRUR¢**": END 


and in direct mode the subroutine may he cailed, or this Une entered: 


OP 18,8,15: 1N1$,0,09: 75,03 
whare I've used standard abbreviated forms of the commands to eane the effort of 
typing them in at tho keyboard, 


Thie checkliat of points which are relevant to CBM dink Fler may aeam rather 
daunting, and [ suppose actually /s rather daunting! Euwever, it In a fact that these 
dink drives are no more difficult to program than many othern. The short demonastrat- 
fon programa in the next sectlon should enable anyone with enthiuelaam ta get the foal 
of theas varloua commanda and practical requirements, Longer demonstration uutines 
ace available on Commodare's demonstration dinks; | have tried fo keap theae short #0 
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that they may be keyed in without too much effort. 


Demonstration programs: {J} Sequential files 





DEMONSTHATION OF SEQUENTIAL FILE - WRITING TO DISK, (BASIC 4) 


S SCRATCH "SEQ FILE", 01 
10 DOPEN#1, "SEQ PILE" DL, ® 

20 FOR J « 1 TO 10 

30 I$ = "RECORD NUMBER" + STRS(F} 
40 PRINT#1,X$ 

45 PRINT X9 OS$ St 

SO NEXT F 

60 DCLOsE 


This specimen program writes 10 records, which consist of ‘RECORD NUMBER 1” 
through ‘RECORD NUMBER 10'. They are held in a file called 'SEQ FILE' which is on 
drive 1; I've assumed a test diskette is loaded into that drive. Drive 0 is, of course, 
just as good! The program works in this way: 


Line 5 erases the previous file {if any) of the same name. The program can thus be 
run repeatedly without %file exists error. Alternatively, line {0's file name in 
quotes can be preceded by '@’, which opens the file, replacing eny previous 
file as though it were scratched. This construction may be risky to use, 


Line 10 opens a disk file, on drive 1, for writing. It is a sequential file called "SEQ 
FILE", How ts the Disk Operating System able to know the file is not relative? 
As we'll see, a newly created relative file has a length-of-record parameter, 
which is absent here, So a sequential file is assumed, and 'W' tells the system 
that it is open for writing, So the necessary buffers are opened in the disk’s 
internal RAM, the name is recorded in the directory, and pointers ar: set which 
will enable the new file to be PRINTed to, in sequential order. 


Lines 20 - 50: the toop, with its variable J, controls the disk write operation. The 
figures in the example cause 10 records only ta be written. Line 30 assembies 
an individual record, X$. It's exact form is not important to the demonstration, 
but ['ve made each record different from the others, so that on reading the file 
it's eaay to check whether the recorda are, in fact, in the right sequence. 


Line 40 printa X$ to file number 1, which was the number assigned in line 10 to our 
file ‘SEQ FILE’. Just ae though the record were printed to the screen of the 
CBM, a carriage return follows PRINT#1,X$, 80 the records are correctly sep- 
arated, (if line 40 is rewritten PRINT#1,X$; with a semi-colon, carriage return 
fs not sent, and the records will be concatenated in a long string. The result 
wlll be too tong for INPUT# to cope with; but GET# will successfully read the 
string character by character). 


Line 45 iy part of the demonstration, and would not normally appear In a finlshed pro- 
gram, except perhaps a utility routine to check the operations involved in file 
handiing. It prints the record, the disk status string DS$, and the CBM status 
variable ST to the screen, where they appear in ten rows. These rows should 
be practically Identical, showing DS$ as 60,0K,00,00 and ST as 0, only X$ vary- 
Ing between ite limits of RECORD NUMBER 1 and RECORD NUMBER {0, 

NUTE; Channel 15, to read DS$, ls opened by the system, and need not be 
explicitly used in @e program run by BASIC 4. 


Line 60 clone fe(s). DCLOSEAL ln this example han the sama effect, 


DEMONSTRATION OF SEQUENTIAL FILE ~ READING FROM DIOK. (BABIC 4) 


100 DOPEN#1, "SEQ FILE" ,O1 
110 FoR J « 1 TO 12 

120 IMPUT#L, 19 

125 PRINT 19 083 AT 

120 MEIT J: DCLOSE 


Une 100 opana "AEQ FILE”, on drive 1, for read, an 'W' and 'L’ are both absent, 
Vinod 110-130 perform a loop which inputa records, Fach ia printed to the screen, with 


both mtatua variables, Note the effect on DS$ and ST of reading an ‘11th record’. 
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DEMONSTRATION OF SEQUENTIAL FILE -~ WRITING TO DISK, (BASIC< 4} 


53 OPEN %5,8,18: PRINT#I5, "SCRATCHI;SEQ FILE" 
10 OPEN 1,6,2,"2:SEQ FILE,SEQ, WRITE" 

20 FOR J = 1 TO 10 

30 X$ = "RECORD NUMBER” + STH$(J} 

40 PRINTAL,X$; CHR${13); 

43 $=ST 

44 1NPUT#15,£1,ER$,52,E3 

45 PAINT X$ E1 "," ER$"," E2 "," B83; 

SO NEXT J 

66 CLOSE 1: CLOSE 15 


This program has the same effect as the earlier (BASIC 4} version to write to disk, 
and sends the same infermation to the screen. BASIC 4 can run this progrem, or the 
other, rather simpler, version, but BASIC<4 cannot run that version bevause it is not 
equipped with the disk command keywords, The line-numbering in each program is 
similar; lines 43-44 above are concerned with (i) saving ST. (ii) reading the four 
messages which correspond to the parts of DS$. ST could be printed in line 43; the 
gole reason for preserving it till later is to format line 45 in the identical way to that 
of the other line 45, 


Line § opens the command channel, and sends a ‘seratch' command to delete ‘SEQ FILE‘ 
from drive 1, The abbreviation PRINT#15,"S21:SEQ FILE" is equally correct. 


Line 10 opens 'SEQ FILE' on drive 1 for write. Note that the secondary address may 
be any value from 2-14 which isn't yet allocated. Again, the abbreviated form 
OPEN 1,8,2,"2:SEQ FILE,S,#” is as good (and corresponds more accurately to 
what is sent on the [EEE bus to the disk). BASIC 4 sends the same messages 
as BASIC<4; the syntax is easier because some of the operations, like opening 
the command/error channel, and finding an wnused secondary address, are 
built Into BASIC 4. 


Line 40 iNustrates the anti-linefeed manoeuvre necessary with BASIC<4. The character 
with ASCi[ value 13 is, of course, curriage return, 


Lines 43-45 have the same effect ag PRINT X$ DS$ ST in spite of their more formidable 
appearance, The four 'error' parameters are read from the ‘error channel’. 


Line 6¢ No DCLOSF exists in BASIC<4, so ail the files muat be separately closed. 


DEMONSTRATION OF SEQUENTIAL FILE = READING FROM DISK. ({BASIC<4) 


100 OPEN 15,8,15: OPEN 1,8,2,"1;GEQ FILZ,85#Q,RRAD" 
110 FOR J = 1 TO 12 

120 INPUT#1,X$ 

123 8=ST 

124 INPUT#15,#1,RR$,22,E3 “ 

125 PAINT X$ £1 "," ERS ",” £2 "," E3; 8 

130 NEXT J: CLOSE 1: CLOSE 15 


Again, this program is identical in ita effect to the BASIC 4 version. 


Line 100 opens tue command channe! and also opens file number 1 to the sequential 
fille 'SEQ FILE' on drive 1 for reading. The secondary address, and device number, 
are chosen aubject to the samo restrictlens on outlined above in the paragraph on line 
10. Device number 9 has been assumed throughout. 

The sereen uppearunce of the Eile ag it's read should, ad la WASIC 4'4 version, 
vonalat of 11 fines, the firat ten meade up af (RECOKD NOMBERT to ‘RECORD NUMBER 
10°, each foltowed by diak alatusa values U,OK,U,0 and CHM stutua of 0. The very leat 
record (10) has ST set to 64, which shows that a record im the lant record In the file. 
The attempt te rend beyond the ond of fle hag effects which vary slightly with the 
ayntom Jn use; HASIC 1, for example, appeard lo return the liat record, whereas 
later BASICo return the carrlage return character Inatend. 
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Demonstratlon programs: {ii) Relative files 


DEMONSTRATION OF RELATIVE FILE - WRITING TO DISK. (BASIC 4 AND DOS 2+) 


1 REM NOTE “W" FOR SEQUENTIAL WRITE ONLY; GIVES ?SYNTAX ERROR WITH REL 
2 REM NOTE OPEN FOR BOTH RPEAO AND WRITE IF RELATIVE FILE 

3 REM HOTE USE OF “RECOFD#”. AND ITS SYNTAX 

4 REM NOTE GET ERROR 5@ OUPING WRITE AS EACH BLOCK OF 256 BYTES IS USEQ 
S REM NOTE CENGTH OF 217 RECOFOS ARE 2@ LONG + CARRIAGE RETURN 

6 REM NOTE “RANQOM’ GRDER OF FEROBACK IN LINE 216 

7 REM NOTE IF LINE 22@ ES OMITTED, FILE WILL BE READ SEQUENTIALLY 

18 OOPEN#2,"“REL FILE" .O1,L2t 

28 FOR J = 1 TO 38 

38 X# = “RECORO NUMBER"+STR#< J> 

40 XS = XS + LEFTS< "a ekkee eee” .2G-LENC KS) > 

SOQ RECOPRO#2 .<¢F>-1 

68 PRINTH2, KF 

70 PRINT X* DSF ST 

89 NEXT 

98 DCLOSE 


The program is quite similar to those which write sequential files: the file is created, 
thirty records (in this case) are written to it, and the records, together with the disk 
status variables DS$ and ST, are printed to the screen. ' 


Line 10 opens a file called 'REL FiLE' on drive 1. Ita record length is specified as 21. 
The file is opened for write, but 'W' as a parameter generates ?SYNTAX ERROR 
because of the implicit confusion between a relative file (signalied by L..) anda 
sequential file. 


Linea 20 - 90 comprise the loop which controls the way records are written to disk: 


Lines 30 - 40 generate a string variable X$ of length exactly 20 bytes. (The twenty- 
first in a carriage return}. Leading asterisks pad X$ to the correct length, like 
this: ¢*e*RECORD NUMBER i. {It ig not necessary to fill the record space in this 
way; shorter - but not longer ~- records may be used). 


Line 50 uses RECORD# to postion the relative file pointer of file number 2 to the Jth 
record's first byte. J is bracketed, as required by BASIC 4 syntax. Thus as 
the loop executes, RECORD#2,1,1 then RECORD#2,2,1 then RECORD#2,3.1 ... 
set the pointer to records 1,2,3,.., and so on. 


Line 69: in this way. record number J is printed into the space allocated for It by DQS. 


Line 70 printa the record, the disk status variable 0S$, and ST to the screen in 3¢ 
rowa (the Cirst few will be lost as the sereen scrolls), This behaves almost 
identically to the sequential demonstration. However, at intervala, error 50 is 
signalled in DS$. This iy not a serlous error, but mcana only that the relative 
{lle ia being expanded to incorporate ita new dita, (See the entry in Chapter 7 
under DS$). Siace one sector stores 254 bytes, and our records occupy 21 bytes, 
Message #50 iz generated about every 254/21 = 12 of so records. 


Line 90 closes the file. 


DEMONSTRATION OF RELATIVE FILE - MEAQING PACK DISK. (BASIC 4 AND DOS 2+) 

aun DGPLHWE "PLL FILE’ OL : 

210 FOF So 36 TO STEP <t 

220 PECKPONZ, 6 JO,L 

730 IMPUTHeZ 48 

240 PRINT “ae O54 ST 

250 HEAT 

209 OLLOSE 

Thik exampie should be self-explanatory, However, note the non-sequentiat arder In 
While cecorde aro reteleyed. Jf [ne 280 da repineed by 220 INPUT “RECORD NUMMER”, J 
and Wne 250 by 380 GoTo 210 frua reintlve oc ‘random acegaR can be demonstrated, 


nen ny . ‘ 
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VEMONSTEATION OF RELATIVE FILE ~ WRITING TO DISK. (BASIC<4 AND DOS 2+) 


“he following example duplicates the effects of the BASIC 4 programs which we have 
ust looked at. The only difference lies in the fact that the version of BASIC in use 
leesn't have the special disk-controlling keywords of BASIC 4, Apart from thia, things 
ire much the same: DOS still has to be version 2 (or presumably later versions when 
hese arrive on the scene), net DOS i.x which hasn't the required relative file capac- 
thes. 


10 OPEN 2,8,3,"1:RZL FILE,L" + CHR$(21): OPEN 15,8,15 
26 FoR J = 1 TO 36 

90 X$ = “RECORD NUMBER" + STRS<{J} 

40 X$ = X$ + LEFTE("*eeeeasvewewses" 20-LEN(Z$)) 

SO PRINTP1S,"P" + CHRS(2) + CHA$(J) + CHRS(O) + CHRS(1) 
€0 PRINT#2,X$: 5 = ST 

66 INPUT#H#I5, £1, ER$,82,E3 

70 PRINT 1$ 51 "," ERS "," B2"," £3, 8 

80 NEXT 

90 CLOSE 2: CLOSE 15 


Zach line duplicates the corresponding line of BASIC 4's version, with the exception 
wf the additional line, 65. This igs interpolated purely to fetch the messages from the 
tommand channel which correspond to those of DSS. 


tine 10 may need some explanation: OPEN, with the format listed here, opens for rei- 
itive access with DOS 2+. BASIC 4 sends exactly the same string to the [EEE bus, In 
spite of the apparent differences in syntax. The same thing ls true of line 50, which 
s equivalent to RECORD. The secondary address of the relative file (i.e. %, here), 
the low and high bytes of the record number, and the byte position, are understood 
xy DOS to be the four bytes after P. 


DEMONSTRATION GF RELATIVZ FILE - READING FROM DISK. {BASIC<4 AND DOS 2+) 


200 OPEN 2,8,2,"1:REL FILE": OPEN 13,8,15 

210 FOR J = 30 TO 1 STEP -1 

920 PALRT#15,"P" + CHRS(2) + CHR$(J} + CHA$(O) + CHRS$(1) 
230 iNPUT#2,X$: 3 = ST 

235 INPUT#W15,82,£R3,22,E3 

240 PRINT X$ EL "," ERS "," E2"," £3, 8 

250 NEXT ' 
260 CLOSE 2: CLOSE 15 


This program reads back the records im the reverse order to that in which they were 
written, to demonatrate the ‘random access' permitted by this type of file structure. 
The record numb2rs vary between 1 and 30, 80 there is no possibility of attempting 
to read non-existent recordy. However, a8 suggested in the last example, moditying 
ne 210 to 210 INPUT “RECORD NUMBER“; J and line 250 by 250 GOTO 210 erlables the 
user to calf up any of the records, in the same manner that a record is retrievable by 
a database system. Because of the structure of line 220, the maxinium value of the 
record number js 255. To increaae this to the allowable maximum of 65535, linea lke 
these need to be Introduced, so that the RECORD statement in Ung 200 tas both low 
and high bytes programmuble: : 


218 JM = 3/256: JL = J AND 255: REM JH*HIGH, JL<LOW, BYTES OF J. [JH IS ROUNDED 
220 PRINT#15, "RP" + CURS$(2) + CHAS(JL) + CHRS(JH} + CHRS(i): REM IN THIS LINE) 
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Demonstration programs: {til} Program files 


Program files are not data storage files in the same way that sequential and relative 
files are: they do not hold potentiaily enormous amounts of data in a convenient form 
for reading, processing, and output. Instead they store consecutive bytes directly 
from memory, together with the information required to reload the same part of RAM 
with the identical data. In the CBM system this is accomplished by storing two bytes 
at the atart of the file which hold the loed address. Subsequent bytes are read and 
stored into this address and its following locations, until the file ends. The very last 
byte is not stored into RAM. (VERIFY uses exactly the same procedure, except that 
the bytes are compared, not stored, with RAM locations}, Both BASIC programs and 
machine-code programs and routines are stored like this. Consequently. 


DSAVE "BASIC TEST PROG" D1 :BASIC 4 
BAVE “1:BASIC TEST PROG",3 BASIC<4 


write a program file to disk called "BASIC TEST PROG’. The program written is the 
one which is currently in memory. (If the start-of-BASIC and/or end-of-BASIC point- 
ers are altered, other consecutive RAM wil! be saved under that name, See SAVE in 
Chapter § and DSAVE in Chapter 7 for more on this subject. As a further example, 
the SUPERMON and EXTRAMON programs lock like BASIC, but include a long chunk 
of machine-code, which the program causes to relocate into the high end of memory. 
It is only possible to SAVE or DSAVE such a composite program by altering the end- 
of-BASIC pointers so that they also include the machine-code). 


«9 "1:4 /C PROG", 08,0334, 037F 


ls a typical command to save a program-file called 'M/C PROG! onto drive 1 of disk 8. 
All the code between $0334 and $037E is saved. 


Files of this sort can be read and written almost like sequential files. In fact, 
some proprietary software (e.g. 'Wordpre')stores ita files as program files, and these 
can be examined and written or rewritten in this way. Similarly BASIC programs and 
machine-code routines are readable and writeable at will. The OPEN command must be 
the BASIC<4 type, since BASIC 4's file-handling hasn't concerned itself with these 
comparatively advanced techniques. Alt that is required is the use of 'P' as a paramet- 
er, when opening the file for reading or writing. Let’s look at a few examples of the 
kind of thing that can te done. 


{a) Finding the load address of program files. This Is helpful with some types of mach- 
ine code, and can be useful with unusua! BASICs where the normal $0401 start has 
been overridden. All that is needed is something like this: 


10 INPUT “FILE MAME, DRIVE NUMBER"; N$,D$ ; REM E.G, M/CODE#1 ON DRIVE 0 
20 OPEN 1,6,2,D$ + 7:" + NS + "PRY : REM E.G. "O:M/CODE,P,R" 

30 GET#L,X$: IF X$="" THEN E$=CHRS(0) 
35 EeASC(X$) 

40 GET#1,Y%: IF Y$="" THEN Y¥$<CHAS(O) 
45 Y*ASC(Y%) ; REM... AND Y¥sHIGH BYTE 
SO PRINT “LOAD ADDRESS I8 “ E+ 256*Y 


+ REM X=LOW BYTE OF LOAD ADDRESS ... 


(b) Writing loadable machine-code or other routines directly onte dish. An assembler, 
for example, might oe required to assemble code Into an area of RAM already occupied 
by code. The normal process of putting the code into RAM, then saving the result, ja 
in thin cane unworkable. However, by writing the load address to disk, followed by 
bytes of machine-vade, uny aren of RAM can be made the subject of a loadable file, 
even inkeky areas like the zero: page (well, up to a point!) and also Inte areas like 
fereoh RAN. 


OPEN 1,8,2,"0:CODE,P,®" 


PRIMT#! CHAM (2 CURB (4); : M8 LOAD ADDRESS 18 $0401 

PRINT#1, CHR$( 147) CHASLOICHRS{ 136) CHRS (157 }CILRS$ (0 )CHRS (128 CURE (292) CHRS (208) 
CHR$(249)CHRI (98) 

CLOBE 1 


This prints « simple tnachine-code string to a file called 'CODE', If this ia LOADed, 
SVS 1025 will cause the code to axucutoe; jt prints 256 different charactura on the 
screen, . 
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inenumbers, and within the program itself, tokens, variables, and special characters 
(punctuation, quotes, REM, DATA, and meaningless spaces). Examples may be found 
in Kllobaud-Microcomputing (R W Baker, Sept.'80) and CPUCN (Jim Butterfield, Vol.? 
#8). When using a program file, in additlon the two leading bytes. which almost always 
ire l and 4, need to be read and subsequently ignored. CATALOG in Chapter 7 has 
a BASIC program, designed to read e@ disk's directory, which shows the sort of thing. 


{d) Processing BASIC (or other) programs. By apening @ program, reading it byte by 
oyte, and rewriting the result to another file, a number of editing manoeuvres are 
possible; for example, merging may be accomplished by writing one program up to a 
tertain linenumber, then writing in turn whichever linenumber is next. The link add- 
resses have to be preserved. Machine-code may be processed in the same way, for 
example, one could read it, replacing predefined combinations of characters by others. 
This may make it possible to painicssiy search for identifying messages and so forth. 
The example shows how two programs (BASIC) may be appended, giving a third. Note 
the handling of the final zero terminating byte of the first program, which has to be 
replaced by the first byte of the appending program. I haven't included commands to 
Input file names, format the screen, or check DS$, to gave spnve; 


100 OPEN 2,6,2,"0:PFIRST PROG,P,R" 

110 OPEN 3,9,3,"0:BOTH PROGS,P,W" :REM THIS IS THE NEW COMPOSITE PROGRAM 
120 GET#2,Xx3 

130 Y$=X$: CET#2,X$: IF ST <> 0 GOTO 200 

140 IF Y$="" THEN Y$=CHR$(0) 

150 PRINTS3,Y$; 

160 GOTO 130 

200 CLOSE 2 

ZL0 OPEN 4,8,4,"0:SECOND PROG,P,A” 
220 GET#4,¥$: CET#4, ¥$ 

230 GET#4,¥$: IF ST <> @ GOTO 300 
240 PRINT#3,¥$; 

250 GOTO 230 

300 PRINT#3,CHRS(0); 

310 CLOSE 3: CLOSE 4 


The point of the coding in linea 120-160 is te copy the whole contents of the program 
file called 'FIRST PROG‘ into the file ‘BOTH PHOGS', except for the very last byte, 
which ig the zero terminating byte. Hence line 130, which continually reads the next 
character X$, testing for end-of-file with ST, while writing only the previous charac- 
ter. By Jine 200 file aumber 2 is finished with; file number 4 is opened, and the entire 
contents of ‘SECOND PROG’ written te the end of ‘BOTH PROGS’, including the end 
zero byte. LOADing ‘BOTH PROGS' will reveal a correct append of the programs. Note 
that line 220 throws away the loa address of SECOND PROG; this is now subsumed 
under the original program's inad address, and is not needed, Note aiso lines 140 and 
240. These are needed to cure a small bug caused by the CEM's difficulitern with the 
null character "" and CHR$(0), The same conversion has to be dene when construct- 
fons like GET#1,X$; PRINT ASC(X$)} are being uacd. 


Another highly interesting application is in modifylng HASIC; the example that 
follows Is based on u routine culled 'LOCKSMITU', which adda code to the start of 
a BASIC program (not BASIC |, however) so that on LOAD, the stop key ls disnbled 
by the usual interrupt address + 3 method (which also turns off the clock, Ti}, and 
sereen-clear, HUN, and carmage return are fareed into the keybourd buffer, The 
program In thus made to RUN simply on LOAD, (Tha process in more complex “than lve 
made it weem here), The pragram ‘protected’ in this way ds comparatively iavulnerabie 
to lating, but of course given the correct approach lx rither eusy to brawk. Tha exam 
ple tikes a program on drive 0 called 'HASIC PROG’ and rewrites It te drive 1 19 
BASIC PROG AUTO’. Thess namen nee used for conveniences onty; obviously propor 
Input and furmatling routines enable the pragram to operate in a user Pfrivncly way. 
The program itaelf con te locked. Nota thal the loud addrens In $000, the bottesn of 
tho atack. 


:REM PRINT SINGLE CHARACTERS TO THE NEW FILE 


;REM PRINT SECOND PROG TO NEW FILE 


et 


f 
| 
“Moe only the stack te overwritten, but the INQ vectur La changed (twice), the reaagt 
vector celled on Stop, M1 te used and « routine updates all the BASIC pulntere. | 
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‘e) Analysing BASIC programa. As we've seen in Chapter 2, BASIC is a complex 
structure, and a program to deal with it needs to take account of link addresses and 
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100 OPEN 2,8,2,"0:BASIC PROG,P,R” 

110 OPEN 3,8,3, "0: BASIC PROG AUTO,P,W" 

120 FOR J = 0 TO 1: PALNT#3,CBR$(J);: NEXT 

130 FOR J = 0 TO 255: PRINT#3,CHR${2};: NEXT 

140 FOR ¢ » 1 TO 3: PRINT#3,CHA$(0);: NEXT 

150 READ J; IF J = 999 GOTO 200 

160 N © N+ 1; PRINT#I,CUR$(J);; NEXT 

200 FOR J = 1 TQ 510-N: PRINT#3,CHA$(O);: NEIT 

@10 GET#2,X$: 8 = ST: IF X$ = "" THEN I$ & CHR$(O) 

220 PRINT#3,K$:: IF S = 0 Q6TO 3210 

300 CLOSE 2: CLOSE 3 

$00 DATA 165,144,164, 145, 16,12,24,105,3,144,1, 200,141, 130,2,140,131,2 
$10 DATA 162,19, 189,84, 2,187,111, 2, 202,16, 247,154, 169,1,72,72,72, 72,72, 169,222 
$20 DATA 160,2,120,193,144,132,145,88,169,4,193,158, 165,40, 133,42,165,41,133 
$40 DATA 43,160,0,162,3,177,42,230,42,208,2,230,43,201,0,206, 242, 202,208,241 
640 DATA 108,148,0, 147,32, 213,13,0,0,0,0,0,0,0,32,234,255,169, 255,133,153,76 
$50 DATA 0,0,0,0,0,0,0,0,0,0,0,0,9,0,0,0,0,0,0, 108, 252, 255,999 


6.5 CBM diskette formats 


&; Disk drives 


Overview of data storage on diskette CBM disk drives contain their DOS in ROM 
chips, and so the entire capacity of the diskette is available for files. Except, that is, 
all the housekeeping details which are necessary to a file-handling system. These are 
held on a single track (track 18} in 2040/3040/4040 diskettes, and on two tracks in 
the larger-capacity 8050 (tracks 38 and 39). This is a very standard arrangement. 
The central position is sefected to cut down on track seeking time. Note that Commod- 
ore documentation numbera its tracks starting from 1, 80 the first track is track 1. 
This is not universal; it seems to be used because ‘track 0’ is used as a special end~ 
of ~-file indicator. The sectors are numbered from 0, on the other hand. 

There are really only three distinct types of housekeeping information on disk, 
and programmers who are interested in delving into the niceties of disk programming 
can write utilities to examine them. The first, on track 18, sector 0 in the -406 range, 
and track 38 sectors 0 and 3 in the -50 machines, holds mainly the block availability 
mep, or BAM, of the disk, and the ‘directory header’, which is the title of the disk 
and ite i.d., as written by HEADER or Disk NEW. A BASIC program, 'VIEW RAM’. is 
a utility program on most demonstration disks which reads this area and translates the 
bits (which are on/off) into sector (=block)} availability (availabie/used). [t reads the 
Qisk's name and i,d. too, and calculates the number of free blocks on the disk by a 
running calculation. 

The eecond region is the remainder of the directory: this ls a chain of sectors, 
which holds a record of each file, Ita type, its name, and its position on disk. So far 
aa 1 know, Commodore don't supply a utility to read these sectors. Most of the inform- 
ation in any case is visibie on the directory. The exception ie the pointers to the firat 
track and sector of the file, which is the first of what may be a very long chain of 
sectors. With one’s own utility program, these detaila may be displayed on the screen 
or In hardcopy. 'DISPLAY T&S’ prints sectors, without following the chain. 

Thirdly, the majority of the disk is occupied by Ita files. These are generally 
Chained together, with a final terminating block. In principle any file can be traced 
from Its directory entry through all its sectors, This can often be a valuable exerclac, 
and hae practical applications In several typea of error-correction, error-recovery, and 
disk revival routines. 

Before examining each of these three subdivisions In greater detali, we will look 
at the arrangement of sectors on CHM diska. The arrangement (more sectors at the 
Outer tracks, fewer at the Inner) is unique to Commodore, to the best of my know- 
ledge. Thi« table aummartaes the current situation: 


SECTORS: 





*Includes directory trackia),- 


D oencidlaneabaemnmnhdhirtden hitmen teetmeten! ihesieheiieanell 
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The Oirectory Header and Block Availabillty Map {BAM). 


8050 
BYTES: Track 39, sector 0 


Pointer to BAMI 
Format: € 





__2¢n0 | 3040 08 
Track 18, sector 6: 


Pointer to directory _ 
Format: 3 eae A ‘Or ¢ 
a-f47 | BAM, 180 bytes in total. Name of diskette + 
_Each of 35 tracks has 4 bytes shift_spaces 
Name of diskette + shift spaces Diskette's i.d- 
to make length 16 characters xC (version) 
Diskette’s 2 character i.d._ t 

















14-161 




















Painter ta BAM? 
format: € 

Tracks 1 & 51 

BAM1: 250 bytes. 
Each of 50 tracks has 
a 5 byte entry. 





"BLOCKS FREE' may appear here} 








735 bytes. 
Each of 27 tracks has 


5 byte entry. 





he main features of the BAM and disk identifle- 
ation in the smaller drive units (2040/3040/4040). The diagrams on the right all obtain 
to the 8050 drives; because of the larger storage capacity, and probably alsa to silow 
for future expansion, 3 sectors are used for the date which could be held in 1 sector 
onty on the smaller diskettes. Most of the first sector is unused; BAM is divided 
into two parts by track, and the first of these sectors holds pointers, a dink format 
byte, the range of tracks for which {t holds the BAM, and 250 bytes devoted te BAM. 
Thia formula may be repeated indefinitely: this makes futureexpansion possible with 
(yome) compatibility. Not all the small detail (e.g. features like shifted apaces, as 
Opposed to null characters) appears In these diagrama. For any disk drive, these 
less Important featurea can be checked fuirly eaaily with "DISPLAY TaS‘ or sume other 


similar utility program, 
What ts the structure of entric 


The left-hand diagram above shows ¢ 


4 In BAM? Ae the tablea show, the shorter tracks 
of the smaller dluk units have a 4 byte entry in thelr HAM, while the 8050 uses 3 
bytes to map Its tracks, The principle in each casa js the sane. The BAM [a split Inte 
49 or 5s, 80 that the 10th track's map starts at the 37th byte or the 46th byte, and 
takes up 4 or 5 bytos, The first byte stores the free sectors in the track. This par- 
meter ia used when the directory computer the total number of blocks free, The Jor 4 
remaining dDyten, naturally, have 24 or 32 bits in total. Fach of these reflects the 
atatun of the correspondicy sector in that track. Since ihe largest number of sectors 
por track in the 4640 type drive In 21, while the corresponding Gyure fer the 8050 ts 
29, It in cloat why the 8050 needs the extra byte In each track's map. Extracting the 
relevant bit in a program In a bit tricky. The BASIC botow shows the method: suppose 
wo ere iooking al sector number S$ In a track, We can find the byte which holds the 
retevant bit, by counting the correct number of 4 or S hyte units, thea picking the 
tnd, ard, 4th, or, with 9050, perhaps Sth byte, If thin byte In B, 


atcs AND 7) AND B finds the bit valuo; if this la sero, the sector in allocated; If 


not, it Ja mw frase aector. 
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The Disk Olrectory 


The directory - the list of files stored on a diskette - 19 contained in a single track 
following the header details, which occupy 1 sector. Models 2040/3040/4040 use track. 
18; the 8050 uses track 39. These tracks respectively contain 20, 20,19, and 29 sectors. 
leaving 19,219.18, and 28 after subtracting the header's sector. Each sector has space : 
for 9 files, so the maximum file storage of these devices is 152,152,144, and 224 files 
in that order. A diskette can be entirely filted, therefore, if its files average about 
IK bytes with the smeller units, or 2K bytes with the 8050. If the average file size is 
amaller than this, the directory will run out of space before the diskette. 

Directory blocks are chained in the usual way, the first two bytes pointing to 
the track and sectar holding the next directory block. The track pointed to is always 
18 or 39 of course, except for the final sector, which has a zero terminatcr. The order 
of sectors, as with data storage, is not sequenUal, but, to cut down the time spent 
waiting for the disk to rotate beneath the head, distributed around the disk at about 
180° intervals. Each directory block is divided into eight subdivisions of 32 bytes. 
The first two bytes are unused, except in the very first such subdivision, where they 
are used as the linking pointer. This table shows the overall structure: 


8050 
Track 39, sectors 1-28 


0-31 Linking track and sector pointer + file entry 1 in sector 
3283 File entry 2 in sector 
4-95 File entry 3 in sector 

















96-127 ile entry 4 in sector 
128-159 Fife entry 5 In sector 


160-191 
192-223 
228-255 


ile entry 6 In sector 
File entry ? In sector 
File entry 8 in sector 











Each file entry is formatted as in the fotlowin 
g@ table. Note that the ret i 
are used oniy in DOS 2+, and do not appear in earlier DOSes, Dar oe ee 


BYTES: | CONTENTS OF A DIRECTORY ENTRY: 


Track and sector pointer in first entry. Otherwise u 
YPE>¥0-ScratchedT Not yet used. mused: 
#80=DELeted 
#8t=SEQuentlal file 
§82=PRG, program fite 
#83-USR, user file 
i = 00 stg ee) nce ate file 
- signals an unclosed file. Such files are remo 
#60 Js a scratched unclosed file, a type to Se waa it dois 


Track and sector pointer to first block of file. 




































~— an Se ree 






File name + shifted spaces (HAO characters). 












Track and sector pointer to relative file's first slde sector. 








Record size of relative fite (l.¢e. parameter following L on opening file). 










7 Replacement track and sector polnter for OPEN@ 







Low and high byte of no. of blocks In file, as shown an the directory, 





on the next page we hay some actual examples roduced with the utillty chilled 
1 PAK e u 
Pp » & 
DISPLAY T&S but output . 
t Pp to « CBM printer instead of the screen. The fontures in 
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Sector 6 of track 18 on a DOS 1+ diskette is dispiayed below, The diskette is nearly 
full; the BAM shows that the outer tracks have 1 + 2t + 5 free sectors, and the 
inner 14 + 87 + 27 + 17 sectors, Note that most of the BAM shows as zero bytes. This 
is because bit 0 is used to indicate that a sector is allocated; and a further byte gives 
the number of free sevtors. All four bytes are therefore zero. The directory track's 
BAM entry is visible in the middle of BAM; 11 sectors are free, so the diskette could 
hotd another 38 files, although they would have to be rather shart. Note also the title 
of the disk and its two-character identifier. 


TYPICAL TRACK/SECTGR CONTENTS OF THE OIRECTORY 


Tz ad@p) egfis FF FF 1F gn <Not directory sector 



























£O ¢ OD BX OG OF BH OB BP GB 
ES + G2 GQ OB OF BE OB BE AG 
FG 4 G8 O@ a8 BA OO BO OG 2A 
FB 1 GO GQ OB G2 BS BA BO 29 


@Q : h r 
as 3fTS if os 989 62 ARs] oe Bg SOE ne ber 
1a 3] QA aH AW BO BA 4B Be OA 5 
18 11 O00 BE Be Ga BG AB OF OD: 
20 :] aa 99 20 CO A@ OG 2G AA [Block Availability Map. 
26 3} 88 ea 08 OO @@ GA BA BO: 
30 ;| aa eo GA AA BB BG OO OD : 
28 Oo Of a0 Ba AQ AA 24 OO : 
4a 12 Qa AG_ 43 29 0A GQ Aa + é 
48 sak sa ta a6\ea aa ea ea | C+ 4—~ Director BAM extry. 
SO + B08 60 OF 08 BG OB GO : Smety Een ee. 
56 :)@0 a4 @6 oO ao AB GH BA: 
6B 310A 94 AQ O4 4H BO HA AB 1 
68 3]@0 9@ HO 4B 29 A BO ADs 
7@ 3| 8A aa 04 G3 Ga OO AG HO 4 
728 1G aa AB a as GB BO BO: 
@9 1/0E FS F7 Of tl 3} [7 wr 
eo ; FF FF 1 11 1] ar ont 
96 1 7 UNIVERSA «Dick Nama 
98 3 + L DEMO 7d. 
AG 4 20 : v1 oe 
Rea Ae : ee BG 2B 1 
BO ; G6 8 OG OB 12 4C 4F 43 6 Loc 
83 1 48 53 29 46 S245 45 26 + KS FREE. 
Co « 29 20 20 20 20 20 20 20 1 
C@ 1 2@ 20 26 29 20 20 20 20 + 
02 1 GB QB CO 42 OO OG EH AO 1 
08 1 3 EA AB AH 28 GO AB 2A + «Unuced, 
’ Sas 
t 
t 
+ 


A typical directory sector is listed on the next page, Note that there are exact- 
ly eight fiio entries. The first two bytes point to another sector on the same track. 
When a directory is read and printed to the screen, these sectors ore read in order, 
and the type of file, file name, and number of sectors occupied are ali read from each 
of these elght entries. and converted Into readable form. The file-type entry, for 
example, is converted from #8L into SEQ, which is more meaningful to the user. For 
thia reason, unless 8 special array-sorting process la used, the aequence of itema as 
dixpiayed by a directory tends to be immuinble, so that sometimes it is worthwhile to ; 


a 


pian the order In which flea are recorded, i 
Becaure of CBM gruphles conventions, the flle-lypo is displayad wa mu reverse 


character on the sector llating ~ t 
fllen are all #82 = program fics. 


he reverse heart {s a sequential file, the remaining 





6: Disk drives 


The first entry in this sector has been marked with 5 boxes; these mean: 
a) The next directory sector is track 18, sector 10, (18 =hexadecima! 12) 
{i} The file-type, #82, shows that this is a program file. ; 
{lil) The program begins at track 22, sector 9. 
{iv} 'BISK COMM2 ¢ is the program's name. 
(v) The program occupies 2 sectors only (i.e. is less than 509 bytes im length). 
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Gh GO. Ga) (iy) 


CG: Plea ey 44-49 S3), Wf OS 
88 1 oo 43 4F 40°40 32 Ag}: K COMmMm2 
e LAG AQ AA AA AA/Oe Be uwa 4 

1 @8 08 aa OA GB 20 (BZ OA) 5 (y 
201 6G 6 G2 16 la qq fa 835 2M) oe 
26 1 48 20 43 4F 4D 4D 33 AG 4 K COMMg 








- 


38 1 AS RB AG AA AD BE aA CO 1 

36 1 882 26 GG 40 BO GO BS AO ; 

46 1 O28 @@ G2 G0 OH 44 49 53: RR OS 
48 3 48 20 57 S2 49 $4 45 AD: K WRITE 
Sa : AG AG AG AB AG BO Be BB : 

SG 1 83 BO GO GA OG O@ G4 GA 2: 

60 1 GA OB 62 OD G1 44 49 53 2: Wh ODIs 
68 1 4B 20 S2 45 41 44 AG RE + K READ 
78 + AG AB AB AG AG OO AB ad ft 

78 : G8 00 68 3G 8G OG O24 AQ 1 

88 « GA BB 82 BO O3 44 49 53 1 a ors 
98 1 48 20 4F 56 43 52 4C 41 1 K OVERLA 
98 1 39 53 AB AB AG OF AO BO 1 YS 

98 1 OS 22 BA 4A OB BO G2 AB 1 

AG + OO BB 82 OD 04 44 45 33 fm DIS 
FE» 468 28 44 49 S2 AD AB AB + K OOIR 

BG 1 AB AG AG AG AB AO AO BB : 

88 5 88 B88 GG BE BF aD OF BG ss 

CB s 08 GO 81 8D 69 26 20 50: a P 
C8 ¢ 45 54 20 44 41 54 41 20 + ET DATA 
OO 1 2@ AG AG AB AO BE OH BO 

06 1 82 O29 Be BO OG OG 39 BO 1 8 
£@ 1 88 8@ B82 17 O8 S52 41 4E 1 MORAN 
EG 1 44 4F 40 2@ 31 2E 3@ 36 1 DOM 1.286 
Fa 5s AB AG AG AD AD BB BG CA 3: 

Fe + 68 OB 86 8M BE BO 22 BS id 


A relative file entry Is slightly more comple 
#Pecimen below shows she extha features ai il a 
in pulbietd oe peace gi ehain, which here starts in track 15, sector 2. 
ength-of-record parameter, The record 
CO 1 00°00 GHAR OSE aS ACY. BEL s in the example are 2t bytes long. 
ce ' 45 AR pleco ce + FILE 
blag AB AA A AafoF a2) (15): eal i 
Hag 0@ Gy 00 oon we 8 ’ miei 
‘ eave our tour of the CLM disk system with a few examples of data at 
machen The next page hos examples of sequantlal file starage, BASIC Giobapac and = 
ic ahr erg From the diskette's point of view, these are oll stored In a similar way, 
Geka na of sectors in which the first two bytes elther point to the next track and 
heel » or contain (rack number zero, to Indicate end-of-flle, with the second oyte 
oe the number of valld bytes in this final sector. 
Toyram filed are siored with an introductory load addresea pointer, so BASIC 
bainn of 64 followed by the RAM dump of the program. Thia caveat of tines inked 
: list each no cuntalning a Hak addrenr, a Ilnenumber, and BASIC, terminated 
fa ie byte, The exception is the very Joat Iino, which haga Unk vidatress of zero 
the Rite the program is fInlshed. Thin pattern can be traced In the HASIC dump 
nfamlicet paye. Note that much of GASIC fa ceadablo, although the tokens oro in an 
BASIC | oem. The program Inectudea machine-codo (it ia DOS Support, which Is a 
basta Hee for machlag code}, Typleally, this Js rather amorphoun. On the other 
+ (ea, which use ASCH! storage, are uaually entlraly readable. Note tho carriage 
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return characters, which are the record separators in the CBM system. Relative files are more complex than the other types, and are stored in a more elab- 


orate manner. Each fite is heid¢ in two parts: the first is the main data storage, which 





ea 1 (i GAOL 99 C3 OF) Fy <——EN Program file resembles a sequential file. The other part is the chain of side sectors, The starting- 
@e ¢ 41 B2 31 32 AC 31 36 t A+l2 al64 \earam ae point of each chain is recorded in the directory entry. Let's first look at the data 
10 5 33 SA OF 20 24 43 38 30 5 Jrm SCOS Next’ sector = track 17, Sectir 10. _ storage. The important point to note is that the file is divided, conceptually at teast, 
16 : 30 @6 34 4 Off 89 BH C23 a4 th ond Addasez $0e01. into equal chunks of data. The size of each chunk is determined by the 'L' parameter 
28 : 28 41 29 83 61 37 36 AT 1 (AD4476 | Ig tink add@sas foar7 ; Ist. U ber = 5. when the file is opened for the first time. It is convenient to refer to these subdiv- 
20 1 SE 314 36 33 39 GA OF 2G ¢ M1E39:8 pa fee isions ag 'records', although by using the byte pointer of the RECORD statement, it's 
30 ' 42 41 53 49 43 32 GO 5@ » BASIC2 P possible to write several ‘records' into the allocated space. A record may be divided, 
36 3 @4 GF @@ 5B C2 29 41 29 1 8) (AD by commas or colons, into ‘flelds': typically, a name and several lines of address make 
40 8 B82 3? 36 A? SE 32 31 33 3: +76 HeI5 up the fields in a record. In a sense, within each record, the dats is read and written 
4% ¢ 31 3A GF 20 42 41 53 49 1 1t@ BASI BASIC param sequentially, in a statement like PRINT#8,A","B$", "C$. Good file-design takes account of 
5@ 3 43 34 @8 OF @4 14 009 99 1C4 @ fl Shee peegmn: the speed of access possible with relative files, and also of the different waya in which 
3803 22 93 14 11 11 ££ 41 14 are | data may be arranged on file. As we have seen, a sequential file is straightforward to 
60 : 11 11 14 411 11 1t 26 20 4 write to: data is written, and finished off with a Keturn; and subsequent data is added 
68 1 20 29 20 20 S53 4E 49 56 UNIV to the end of this, so the result is a long file punctuated by Return characters. 
78 : 45 S2 53 41 4C 20 44 4F 3: ERSAL 0O . Writing to @ relative file isn't quite as simple, because of the fact that at any 
7e@ ¢ 33 26 33 355 SQ 38 4F $2 +: S SUPPOR time a record can be accessed and written to, Suppose record #250 hotds a name and 
OS 6 S54 20 4C 4F 41 44 45 44 + T LOADED address at present; then the program decides that record «250 should be some other 
SG rat qi d2 21 22 12 Lk 1d s name and address, 90 tt calls up this record, and writes the new data into the record. 
98 t 22 08 55 O4.16 98_AZ/OO) >" Mm SEMA of BASIC program, If the new address is shorter than the older one, there is a risk that garbage may be 
96 +(69 90/AA AAR AA AA AA AA : teERII left in the record, Consequently, any PRINT# statement to a relative file not only 
Fee t RA AA AA AA AR AA RA AA: TEI writes {ts data, but also fills the remainder of that record, from its position at the end 
Ae 1 AR AA AA AA AA AAR AA AAs LEP of its data to the record end, with null characters (zero bytes). This must be borne 
B@ : AR AA AA AR AAR AA AA RA s TPE in mind if several PRINT# statements are made to the same record, using constructions 
B8 7 AR AA AA AA AA AA RA AR ee OTE <— Garbage. befor mathine- cole section like RECORD#1, 250,10 to write from byte position 10 in the record. Apart from this 
C6 + RA AR AA AAR AA RA AA AR eg OIE III subtlety, PRINT# is usable exactly like a sequential record's PRiINT#, and a Return 
Cs + AR AA AR AA AA RA RR AP st TUTE character is written in the same way. For these reasons, the easiest way to use 
DO + AA AR AA AAR AA AR AR AR ts TET felative files is to follow these two rules: 
Oe : AR AA AA AA AA AR AR AA LTE (i) Test the length of your data before printing it to disk, to check that it'll fit 
Ee : AA AA AR AA AA AR AA RA TEE the record size; remember the carriage return character. 
E& ; AR AA AA AA AA AR AA RA 2 ESTE (ii) Use a single PRINT# statement for euch record, for example: 
FQ « AA AR AR AR AA AR AA AAR st PTE ET PRIKT#S,N;","34$:°,":M:K$% which writes 3 fields to a record, consisting of a 
Fe : AR fA AAR AA AA AA AA RA STAI EII numeral N, a string N$, and a composite field holding numeral M then string 
@ :(41_ 14)AA AR AA ER EG 77 Vit? MS. 
e6 + 08 G2 E6 79 86 63 BA BD» 7 wR <— Pointers 
1@ +81 81 C9 98 08 SABO eZ vEe eee ohn b oot inking date 
18 + 81 C9 C3 De 33 AS 7709 + .—BI74 —— DATA SECTOR CHAIN: sectors. 
20 1 2C AS 78 C9 O82 OF 26 RA: ,| B, nd 
26 1 69 94 89 Bi 77 C9 BE FO s BHATADe i = 7 Pointers te sectors of data, 
3@ 11169 40 FQ 00 CA B5 B91 Ay TH STOR SECTOR CHAIN: 
eo Powters betwen she - sectors. 

ea ote 28 36 3B 31 20 Wt 0001,P Sequential file. {NOTE: The chalned sectors ure not arranged linearly, but ecattered about the diskette) 
ee 1 98 39 38 32 eC 50 45 5 =8062,PE 
4 } 8 ca 2. a5 - nod Pe : ereeeste Next setter is track 13, section 15. As the diagram shows, relative files have a chain of ‘slde sectors’, which polnt to the 
20 1 45 54 20 fe 36 30 22 35 1 ET esos Sectora holding the actual data. For example, sector 250 haa ita own pointer, which [a 
ras oe 50 45 54.20 44 éO 30 | PET De q n the third aide sector, and consists of its track and sector number. When a record 
30 3 30 30 3 oc <a 46 Ba oO | bos Pet is acceaned, the record tength Is used to calculate which sector(s) hold the tccord; 
30 1 44 49(60)39 30 30 ae oC 1 Dt one? the maximum length of a reiative record is 254, ao two sectora at mont hold It. The 
40 3 5@ 48 54 20 44 49 53 feo) , pet Ds. ‘pproprlate sids-secctor is loaded Into Its buffer, and the pointers for two sectors read, 
401 30 38 30 tegen cs me ‘ae 1 O000.PET 0 the actual data cun be loaded next. Thia la quite an efficient process. To take an 
as on) aa aS oo ae i) Aaa nice Ges actual example, sippose we wish ta read record #400, and the record length is stored 
raat Bs Poi sages Pee ae pees { 46 106. Also suppose that the (ile is open, and one of Its buffers holds a side sector, 
6@ 5 49°59 48 20 (0 48 a 4h pete aat 4 And the other holds a data sector, (The third holds data for input or output). The 
66 1 38 2C 30 45 ca 28 as 49 ; @, PET o1 Tecord atarts at tha 99*#4 = 8J1Uth byte Jn the relntive file of data, In a sequential 
76 1°53 4B 20 44 0) 40 38 31 t Sk 0 001 "yktem, we'd have to rend conwecutive sectors to find thie, fn our relative file system, 
hig ao oe ae ae Ba oOcae: ae iceET though, DOS calculates that the 43idth byte Is to be found In rector 32 (le. #316 

3 34 20 ei, oI Mivided by 254), So arctor 32 (and perhapa 33} t be rend, Where ia rector 32 of 
60 1 82 48 26 44 41 G0) 30 30 1 SK OR BO etnic Chino, F i api ale rete A hae Lt cle 
BR s 31 92 20 40 4% tH 20 44 4 12,PET O t data file? [t's pointers are held in wide acctor number 32/240, i.a. 0. So the divk 
ea. a9 as ap a peaerm fat : ise Sct } in 4earchad for thla sector, which takes a single disk read unlens thin side acctor ia 
90 4 40 30 71 23 cl 50 45 4 5 0013,PET a buffer alrgady, in which cane it can perform tha nuxt step Immediately, which ls 
Ag 28 44 49 539 46 20 44 41 =: ~OISK CA 
A 1 54 41 OD) 30 3G 31 34 2C 6 TA Oda, 
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either from the side sector, or from the prior duta 


the next data sector can be read 
the naximum required by this method. 


sector. Three disk reads are therefore 


Ench side sector is formatted like this: 






Track and sector pointer to next side sector. 
Side sector number, O5. 

Record length of reiative file. 

6 pairs of pointers to every side sector. 

120 pairs of pointers to consecutive sectors of data. 








go that a new side sector can be found with a single disk-read onty. The first pair of 
pointers is the usual DOS maintenance link pointer set, so that the file can be COPYed 
Gin principle} and mot COLLECTed. An extra channe? needs to be kept open by DOS 
for this type of file; one for the side sector, one for a data sector, and the third for 
the data itself, (A sequential file needs only two, holding 4 sector and data respect- 
ively}. Since ten channels is the maximum allowed by the system, apart from channels 
0 and 1, the following combinations of open files are the most obtainable (more files 
may be used in a program by closing some while others are open): 


@ Sequential files 
2 Sequential files 
3 Sequential files 
5 Sequential files. 


3 Relative files 
2 Relative files 
1 Retative file 
0 Retative files 






or 
or 
or 


+ % + 






The first issues of DOS 2.5 (for 9050 drives} permit only a maximum of 6 side 
sectors te exists. This is the same number 46 is available with the 4040 drives, and 
la something of a restriction; "The 8050 thinks it ig three 4040s‘, as I've heard it put. 
A single relative file can't fill the whole of an 8050 disk; three can. This restriction 
will be removed with the third set of ROMs for the 9050. * 

Let's loak at the restrictions implicit in the relative files’ handling. Firat of all, 
the number of records is held as two bytes, and can't exceed 65535, Secondly, the 
Jength of a record can't exceed 254. Thirdly, the maximum number of sectors which 
the file can occupy is limited, by the side sector restriction, to 120"6-720 sectors. So 
the maximum data storage capacity of one of these files ig 720254 = 182 880 bytes. This 
B050 may need to separate what could have been 
Data compression techniques may be 
for 


ig not a great deal, so users of the 
a single file into several of shorter record-length, 
used, particulariy with numerals, and repetitive information should be left cut; 
example, the demonstration programs in section 6.3 of this chapter all write records of 
be stored, as is perhaps 
number of records 
this 


gives tho 8050 figure. Commodore documentation puts the Inngth of a 4040 relative file 
ag 167132 bytes maximum (and implies thet this is a diskette's maximum, not a files 
Thus, 1827 recorda of length L100 can be fitted lato an 


the form RECORD NUMBER x'; in practice, only the x need 
obvious. To calculate the longest available record-length, when the 
ls known, divide 182880 by that number and subtract 1 (for a carriage return); 


maximum, which (s confusing). 
9050 reintive file. 

Another approach In the use of a large sumber of amall flies. Section 6.2 ex- 
‘nverted files! make a sultable slructure for a dstubase; Aa practical 
Juter Silicon Offices retrieval system, (In which relative 
which Includea both a ralailve 


plained how 
®iustration Is the O27 and the 
recarda are recoverabln by @ key such as ‘SMITIH218", 
record number (218) and its own internal rystem, in whieh a serien of short files hold 
a oreletive File nals (ie Sa in sorted 


polaters based on the Initint of the fleld. Thias, 
{Fach new uatey is added 


erder, Froa which the corresponding dita can be reeavered, 
to the relathve fle, and also merged Inte Ula index fle). 


6: Disk drives 

to calculate the position In the side sector which storea sector 32's pointers, read the 

track and sector from thls position, and finally read the disk again. Where necessary, 
! 
i 
1 
a 
! 


——— ae ee emma ame ee Se rd 


aa te may be taportant to have the facility to ators large relative files, = peogram 
Like this one may be useful. [ft 18 ona way (of many} to test the upper itmit of 508 
with relative Ciles. Put a formattod empty dink ha drive @: 

10 POPENSL, "TENT", Lig, 00 

20 FOR J = 1 TO LR : RECORDAL, (59199): EF D5¢963 THEN MERIT 

30 PAINT “MAX,REL. FILE APPROX, =<" 100°! “BYT#87: DCLOSE 





ban 
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6.5 Direct access programming to disk 


CBM direct access Commands Commodore's motives for i i 
whilst supplying very little documentation, seem to Hees been nied. hensiony they 
ride a temporary measure, designed to suggest that relative files and other convenient 
tle handling techniques were available with DOS 1+, when in fact implementation was 
rathee difficult. DOS 2+ does not appear to have been correctly updated, so that the 
Block~Altocate function may not work correctly. There were at the time of writin 
persistent rumours (or to be precise, rumors) that new CBM disks wiil drop thoee 
commands, switching to others and also being 'more supportive’. This remains to be 
seen. The following summary applies to DOS 1+ and DOS 2+, and consequently to the 
fange of 2040, 3040, 4040, and 8050 drives; it may not apply to later versions of DOS 
These drives contain two microprocessors; one of these processes the incoming 
data on the IEEE bus, including the command channel strings and the input and output 
of bytes of data. This shares RAM with the other processor, which In effect is a disk 
controller chip, operating the read/write head, the motors, the encoding and decoding 
of bytes, the error handling, and the housekeeping, including such matters as check- 
ing ulock pulses, and testing cyclic redundancy checks. This processor is less access- 
ble than the other; there's a well-known Butterfield program (see e.g. IPUG, Jan.'8@) 
which in effect enables either chip's ROM to be disassembled. [In its original form it 
i WERtEA for the 2040 drive. Some programs make use of these facilities to provide 
a : igh degree of copy protection. For example, OZZ and ‘Silicon Office' have their own 
Ut routines ta read and write sectors, which are reputed to be different from the 
rainy ae: rill we cenuluns disks are truly uncopyable with the normal CBM 
” ctions. is sort of thing i i - 
Sada decade tanpagol ee a rather unusual, and tends to require co-operation 
i How are direct access commands sent? A special character in the ‘open’ stateme j 
ken cine ‘ype of becsesring is to be used, and DOS allocates a boffer’ ‘This ie 
a ‘channel number i i i i 
bie coer atuidmcatec the wvnlan Pec is identical to the secondary address used in 


OPEN 1,3,2,"#" :REM ASSIGNS A DISK BUFFER TO CHANNEL 2 AND LOGICAL FILE NO. 1 
OPEN 7,6,5,"#6" :REM ASSIGNS BUFFER 6 TO CHANNEL 3 (OR ERROR 70,NO CHANNEL) 


DOPEN includes an irrelevant drive number. GET#1,X$ or GET#7,X$ returns the buffer 
ee (3-12), in our examples. The first format is less trouble, since it searches for 
- ree buffer itself. The channel number occura in all the commands in which sectors 
rr read or written; the BAM instructions (Block-Altocate and Block-Free) don’t use 
BD neither do the DOS memory commands. However, the ‘Ut commands, which jump to 
aati hire ee the 2040 only, to an gxpansion ROM socket), also require the 

tne con isa ote that secondary addresses 0 and t are reserved by DOS for read- 


The examples that follow assume, for conglstency in expoaltion, that 


OPEW 15,8,15 
OPEN 1,8,2,"8" 


have been performed, opening the command channe! as file 
» #15 and a direct-acces: 
ae as file #1, channel number 2 ~ the different numbers to emphasise which canis 
a ts in use. Soma of these commands, those beginning 'B'. resembie disk comm- 
pie as sent by BASIC<4, In that alternative spellings are accepted; the hyphen is the 
re deal ag between the two parta of the command name. Mnemonically, thix can be 4 
umes A colon marks the command nume'ta end. The M‘, or ‘memory', communds are lesa 
th ene In thla respect. They are also intolerant of the use of numeruln or variables 
aoa strings, while "R’ and 'U' commanda are able to deal with numbers ag they 
saalpered (he use Oe at vat with {ts short Wustrations, I've Included fuller 
" Hef "t ACCOsA comm ; B 
ite eaaiaat way te aad he teelor them, ands; looking at examples ia probably 
a should perhaps add that these files, tke afl others, can be closed when the 

ee panes with, Thla nuty cause the diock avallability map to be written to a. 
ie Inet Its updated atutug, and thus make permanent the changes in avctiira which 
nied routines may have carried oul, Conversely, If COLLECT (Disk VALIDATE) Ia 
re phe out ata future time, uasr-weitten secturs, oven though they've bern allocated 
el oe will be do aligented, untona an claborate aystem of polntera has heen included 
oa mle one of the acceptable fila types. Such sectora will then be Iable to be over- 

Hen if file ara subsequently atared on the disk by DOS. For this reason, direct 


. a 
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access files must normally be segregated from files which are maintained by DOS, so 
that an entire disk (or side of a disk, with double-sided drives} may be reserved for 
this form of data storage. 


BLOCK-READ command. Replaced by U1. 


Thia command enables any block on a standard-format disk to be read. The disk must 
be furmatted in the same way as the drive which is reading; in particular, the number 
of tracks must match, so that the stepper-motor intervals are equal. 8050 disks cannot 
be read by -40 drives, and -40 disks cannot be cead by 3050 drives. U1 is the more 
reliable instruction, and ls recommended in place of B-R, which it closely resembles. 
If a sector cannot be read, because of some flaw in the recording process, Block-Write 
can sometimes reconstruct the sector, so (for example) disks which will no longer init- 
falise may be recoverable. 


Syntax: PRINT#i5,"U1"; channel number; drive; track; sector or: 
PRINTE15, "U1: string of four characters" where the four bytes are taken to 
be channel, drive, track, and sector. 

Note that commas, instead of semi-colons, may be usabie as separators in the 
first form, though semi-colons are the recommended character. 

On executing this command, the sector is read into the channel's buffer, and 
the buffer-pointer set to the start, so that characters input from the buffer will read 
from the beginning. If bytes 144-145 only, say, are wanted, Buffer-Pointer can be 
used to shift this pointer. 


Examples: The first example is rather rudimentary; {t prints 256 characters from any 
sector directly to the screen. If these include screen editing characters, the screen 
will clear, shift, etc. 'DISPLAY ThS' works like this, using a decimal to hexadecimal 
conversion routine on ASC(X$}. Remember that X$ must be tested for equality with the 
null string "", and converted to CHR3S(0) when it is nuil, 


10 OPEN 1,8,2,"e": OPBN 15,8,15 

20 INPUT “DRIVE, TRACK, SECTOR"; D,T,& 
30 PRINT#15,"U1";2;0;T:9 

40 GET#1,X$: EF 8T=#64 GOTO 20 

$0 PRINT K$;:; GOTO 40 


The next example shows how a chain of sectors can be followed; all that's needed is to 
read the first two bytes of a sector, and read the corresponding track and sector, 
until eventually the track is recorded aa zero, showing that the file has come to an 
end. The routine prints each track-sector pair: 


10 OPEN 1,8,2,"#": OPEN 13,8,15 

20 INPUT “FIRST SECTOR’S DAIVE, TRACK, AND SECTOR”; D,T,S& 

30 PRINT “TRACK =’ T " SECTOR =."8 

40 PRINT#1S, "Yi"; 2:;0;T58 

80 GET#1,T$: GET#AL, S$ 

80 Iv T$e°" THEN PRINT “TRACK w ZBAQ"; CLOSE 1: CLOSE 15: END 
70 IF 8$<"" THEN S$=CHR$(O) 

60 T«ASC(T$): S=ASC(S$): GOTO 30 


Purther examples occur in RANDOM 1.00, the 8K progrem to procese relative files with 
DOS 1. See Ilnenumbera 4L0ff. for typical read, update and write disk procesning. 
The alternative form of syntax of thia command, and of the remaining Block 
commands, Is lesa convenient to uxe, Bo T shall onty briefly mention It here. (I am 
talking about BASIC programming; in machine-ende it ta casicr ty send a command 
atring on the IEEE bua in the alternative form). It conalats of » string of 7 characters 


1000 CB = “UL:" + CHRS(CH) + CHRS(DA) » CHAS(TA) + CHAS(SE) 
tOLO PAINT#1G CP 


3000 PAINT#15,“U1:" CHNG(CH) CHR9(DR) CHRS(TK) CHA$(BE) 


7AM 2 IS SECONDARY ADDRESS OF FILZ No.1 
:REM END OF BUFFER 
‘REM PRINT CHARACTER FROM SECTOR 





. PEE ILI ER PLS PETE AOE ONS SP RET TU 
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& 





Programming the PET /CBM ~187- 


6: Disk drives 


BLOCK-WRITE command. Reptaced by U2. 


This commend writes the current contents of a specified buffer to any track and sector 
of a disk. Data may be put in the buffer by PRINT#1, in combination with Buffer- 
Pointer if the data ia wanted in mid-buffer. [t may be loaded from another sector, or 
a combination of the two methods may be used to load/ update/ rewrite any sector. 

U2 is recommended in place of B-W. : 


Syntax: PRINT#15,"U2"; channe? number; drive; track; sector or: 
PRINT#15,"U2; string of four characters” where the four dytes are taken to 
be channel, drive, track, and sector numbers. 

The position of the Buffer-Pointer is not relevant to this commmand; it is used 
by INPUT#1, GET#1, and PRINT#1, when reading from or writing to the buffer, but 
the entire sector is written irrespective of the pointer‘’s position. After this command, 
the pointer is left at the start of the buffer (byte 1). 


Examples: The first example writes to every sector in track 1. This may ba used as 
the basis of a test timing program; varying the order in which they are written will 
cause variations in time taken. CAM disks use an algorithm to calculate the position of 
ne ‘next’ sector in a track; the -40 series for example adds about 10 to the previous 
sector. . 


10 OPEN 1,8,2,°#": OPEN 15,8,15 

20 DATA 0,12,2,3,4,5,6,7,8,9,10,13,12,13,14,15, t6,17,18,19,26 

21 REM ORDER 139 YARIABLE. NOTE THAT 8050 UNITS HAVE SECTORS O-28 IN THIS TRACK 
30 FOR S = @ TO 20 

40 READ SE 

50 PRINT#13,"B-P"; 2,2 :REM CHANNEL 4 18 SECONDARY ADDRESS. BYTE POSITION=1 
60 PRINT#1, "MESSAGE" + STR$(S) : REM THIS WILL BE WRITTEN TO THE SECTOR 

70 PAINT#15, "U2";2,0,1,5E :REM D = DRIVE NUMBEA, ixTRACE, SE=SECTOR 

@0 NEXT: CLOSE 1: CLOSE 15 


Note that BASIC<4 will add an extra line feed, CHRS$(10), on the end of the message 
in ine 60, The next example shows @ sector being partly rewritten with PRINT#. Note 
that In BASIC this is accompanied by a carriage retucn character; this is unlikely to 
be wanted if the sector is part of BASIC or machine-code, but is acceptable with files. 
bx avoid the character deing sent, simply finish the PRINT# statement with a semi- 
on, 
240 INPUT "INSERT MESSAGE FROM WHICH STARTING-POINT (1=SECTOR START)"; P 
250 INPUT “MESSAGE”; M$ 
260 PRINT#14,"B-P";2,P 
270 PRINT#1 M$; 


:REM 2 18 SECONDARY ADDRESS «© CHANNEL 
iREM WRITE MESSAGE (COULD ALSQ CHECK THAT 
P + LEN(M$) <¢ 257). 


B-E 
BLOCK-EXECUTE command. 


Block-Execute la analogous to a program LOAD then RUN. It loada the specified sector 
Into its buffer, then jumps, In machinc-langusge. to the start of the buffer. On en- 
tountering RTS it returns to the BASIC program using it. This command ia not often 
Uned, alnce there Is little advantage In its use unlesa the programmer haa detniled 
Knowlertge of the DOS ROM In the disk unit. The Muemory-Execute command Ja similar, 
Ut ith maching-code ls not kept on @ Gdisk sector, but directly PRINTed to memory, 

“0 It la more widriy ured in BASIC ulllitlos. 


Syntax; PRINT#HLS,"B-E"; channel number; drive; track; aector or: 
b PRINT #15,"B-E: ateing of four charactera" where the four bytes are taken to 
@ channel, drive, trsck, and aqctor numbers. 


Examples: Any of the Momory-Execute type of command met with in utiltlea can be 
¥ritten ta a sector on disk, but wlll be vulnerabie to overwriting if COLLECTed, so 
that the disk cannot to an ordinary DOS disk, For example, a palr of routines In 
Transactor (reprinted in CCN, July '81) give the whersaboula of DOS' subroutines to 
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compute the number of free sectors in a diskette (the routine is part of the directory, 
and adds the free sectors as they appear in BAM). The information for DOS 2 and 
DOS 2.5 ts: 


DOS 2: Put disk drive number {0 or 1} in location $12, 
execute routine $DB14, 
ther: blocka {ree are contained in $4377 (tow byte) and $4378 (high byte). 


DOS 2.5: Put drive number (@ or 1) into location $12, 
execute routine $D3E7, 
then blocks free are contained in $43AF (iow byte) and $43B6 (high byte). 


Since the B-E buffer is not fixed, unused RAM locations of DOS are needed; one of 
these is Memory-Written with the drive number, and B-E called, holding this: 


LDA DKIVB/ JSR DB34/ LDA 4377/ STA RAMLO/ LDA 4378/ STA RAMHI/ RTS 


BLOCK-ALLOCATE command. 


This is a BAM command which seta a bit in the BAM low, corresponding to a track and 
sector which the parameters specify. This prevents the sector from being overwritten, 
unless COLLECTed, when the BAM bit will be set high again. If the requested block 
ts already in use, error 65,NO BLOCK is signalled in DS$ or Sy GETHIS,E. Some DOS 
versions return the next avatlable track and sector with the error string. This makes 
the allocation of new sectors very easy, since the same sector can always be requested 
(e.g. the directory header) which is known to be used, and the next parameters can 
simply be read out. This works with DOS 1, but is reported to be unreliable with pos 
2: this of course mukes DOS 2 more unworkable than DOS 1 in this respect. The way 
to get round this bug is to try tracks and sectors in some increasing pattern. until 
error 65 no tonger appears. !deally the pattern should be that of the order of sectors 
used by DOS. The 'next' track and sector is evaluated by DOS according to its own 
algorithms.* The syntax is identical to that of Block-Free. 


Examples: With DOS 1, this type of subroutine will allocate a new T and S: 
1000 PRINT#15,"B-A";D;T;9 
3010 INPUT#15,E,2$,£T, ES 
1020 IF E=O THEN AETURN :REM T AND 9 ALLOCATED SATISFACTORILY 
1030 IF £c>65 THEN COTO ...:REM SRROR-HANDLING ROUTINE 
4040 T=8T: S=ES:; IP T=x18 THEN T=19: REM AVOIO DIRECTORY TRACK 
1950 coTO 1600 :REM ALLOCATE TKR NEXT TRACK & SECTOR AS RETUANED 


DOS 2 requires a more tedious routine; the following is an outline, omitting the detail 
required to test sectors for vulidity. See linenumbers 800ff, in ‘RANDOM L' for an ex- 
ample of the type of test that's needed. Since this routine relies on incrementation of 
the track number, 4 [ull diskette can only be ensured by writing from track 0, sector 
G, rather then starting at the directory track's neighbourhood. 

1000 GOSUB ... :REM INCRPMENT SECTOR/TRACK; AVOID OFRECTORY 

1010 PRINT#1S, “B-A";D,T,8 :REM TEST THE BAM 

1020 IF OS<0 THEM AETUAN :REM T AND 8 ALLOCATED SATISPACTOAILY 

4030 IF D5<>65 THEN GOTO .., : REM ERROR-KANDLING ROUTINE 

1040 GOTO 1000 :REM CONTINUE LOOP 


——= 

















“te algorithm i9 required to generate a wertes of sectora, covering thea entire range 
without repetition, with ataut half a dink's separation betwoon canmecutive aactnra. 
Typically, 1¢ generates avon sectora in macending patra followed by odd sectore in 
descending paire. Exnmple: (1) Set wm constant + 4 the nunder of sectors, to the nearest 
Integer, (1t}) Select two even constants, one greater and one jess than the number of 
aactors, (141) Start with actor 0, adding the constant, subtracting the larger vatue 
when the sector la imponaibly high: when gero, set the aector ta 1 and repeat, But 
aubtrecting tha amalier constant on overflow. 

Conelder track lo of the -40 range, with eectorm 0-20, Jetting o r incroment to 
t@, and our high and low cunstants to 22 and 14, the foltowtng sequence im generated: 

0,10,20,8, (t.e. 30-22}, 10,6,14,2,12,1, (hoa. In place of 0),11,5,(1.¢. at-1M). 
13,5,16,7,17,8,10, exit {om sequence exhausted). 
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B-F 
BLOCK-FREE command. 


This command is the converse of Block-Allocate; it ia a BAM command which sets the 
specified track ond sector bit in BAM high, so the secter is de-allocated. The sector 
stili exists, but ig liable to be overwritten. 


Syntax: PRINT#15,"B-F" drive; track; sector 
The syntax Is identical to that of 'Block-Allocate’. Note that a channel number is not 
required, 


Exampte: The routine de-allocates all the sectors of a diskette. The BAM at the end of 
thia process consists of 1s only. Routines of this sort may be useful in experiments 
with free-format disks without a directory. Note however that de-allocating sectors 
with this command is not necessery; allocated sectors can be written over, ignoring 
the warning of error 65 that the sector has previously deen allocated. 


1000 FOR T « 1 TO 35 :REM 2040,3040 OR 4040 

1010 DATA 20,20, 20,20, 20,20, 20,20, 20,20, 20,20, 20,20, 20,20,20,19,19,19,19 
1012 DATA '19,19,19,17,17,17,17,17,17,16,16,16,16: REM 4040 HAS 18, NOT 19 
1020 READ X: FOR S = 0 TO X 

1030 PRINT#LS,"B-F";0,T;39 

1040 NEXT S,T 


B-P 
BUFFER-POINTER command 


Buffer-Pointer controls the pointer te a buffer used by the ‘Block’ commands. It is 
used both when PRINTing data into a buffer and when reading it out. The rationale is 
similar te RECORD when relative files are used from BASIC. 


Syntax: B-P has only two parameters, the channel number and the byte position. The 
latter normally takes values in the range 1- 255. 
PRINT#15,°8-P"; channel number: byte position 


Examples: Block-Write includes several examples of this command. To illustrate how 
Buffer-Pointer can be used with read, I've written this short example program; it 
reads a sector from the directory, then reads the requested file details from the 
buffer, using the fact that each file's data occupies 32 bytes. 

LO REM DIRECTORY TRACK = 18 OR 19; SECTORS 3 1-20, 1-19, 1-28; DEPENDING ON MODEL 
20 OPEN 1,4,2,"": OPEN 15,6,15 
30 INPUT "DRIVE, SECTOR”; D,S 
40 PRINT#IS, "U1", 2,0,39,9 

$0 INPUT "WHICH FILE”; F 

80 PRIMT#15,"B-P";2;32¢F - 32 
70 PRINT CHR${34); 

80 FOR J=1 TO 32 

20 GET#1,X$: PRINT XS; 

1090 NEXT J 

1190 GOTO 80 


M-R 
MEMORY-READ command. 


MR Cnables the KAM and HOM in DOS to be rend, one byte ata time, by the CBM. 
This hag upplications In dinissembling DOS, pecking RAM ond zero: page. looking at 
BAM am [t In held in memory, ond go on, A new M-R command must de issued for each 
new byte, 


Syntax: PRINT#HIS,'M RK” followed by two bytex oaly. Thess conatcuctlona ure accept~ 
atte: PRINTSIS, "M-R" ;CUAS(BICHRE(D) anct PRINT#LS, “M-AVCHRS C123) CHRSCT) HG 

PRINT#IS “M-R” + "q" 6 7S" caAmong others. The two parnmeters whieh follow "M RY ser 
the low and high byte reapectively of the DOS acdresa ta be peeked. Note tuck the 
form MR" fa the any uceepted form in which this command ean be Insued, The black 
commands ailow “HLOCK ALLOCATE" for example, or other warda with the lnithds it- A. 


;REM OR TRACK « 16 POR 2040, 3040, 1040 
:REM F FROM 1-8 

:REM POINTER MUST BE 1,33,65,97, ETC 
REM QUOTE MAAK 


;REM PRINT DETAILS OF ONE FILE ENTRY ONLY 


+ 
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Examples: The fiest example returns the value of any byte In any location in the 
IEEE part of DOS (i.e. not the disk controller's locations). I've written it aa a sub- 
routine, so that it can be added to a BASIC disassembier and used to disassemble DOS 
ROM in hardcopy form. (Thia is easier than modifying a machine-code disussembier, 
and not all that much slower with a printer). Assuming channel 15 is open, the byte 
held by DOS in location QQ is returned in QQ. So, QQ=63030 returns from this routine 
with QQ=PEEK(DOS location 63030), for example, QQ doesn't signify anything particul- 
ar; I chose it only because it's unlikely to be a variable used elsewhere in & program. 


10000 REM ON ENTRY, QQ = LOCATION (0-65535); QQ RETURNS AS THE DOS PEEK 

10001 REM 

10010 PRINT#1S, "M-R" CHRS(QQ - INT(QQ/256) ©2356) CHR$(QQ/256):REM LO THEN Hf SYTE 
10020 GET#15,QQ$: IF QQ$="" THEN QQ$=CHRS(0) 

10030 QQ = ASC(QQ$): AETURN 


The second example peeks into a region of RAM in which the current disks’ directory 
entries are held, (For a memory map, see a few pages forward). This area will of 
course be peekable by the disassembler too, but this program prints it in readable 
form: 

100 INPUT “WHICH BUFFER? (1=$4200, 2=$4300); B :REM ® SHOULD @E 1 OA 2 

110 INPUT "WHICH DRIVE? (i= -40 , 2=8050) ; T REM T SHOULD BE 1 OR 2 

120 IF T=] THEN T=i44 :REM STARTING-POINT OF 

130 IF T=2 THEN T=6 :REM NAMES AND IDS 

140 FoR JxO TO 19 

150 PRINT#LS, “W-R': CUR$(T+J}; CHRS(65+5) :REM FETCSES AND PRINTS DISK 

160 GET#15,X$ ;REM NAME AND 1.0. 

170 PRINT X3: 

180 NEAT J 


MEMORY-WRITE command. 


M-W enables data to be placed into the disk unit's RAM. This means machine-code pro- 
grama can be written to reside within the disk unit. (n principle thls has many uses, 
inctuding hardware control and alternative software to operate the disk, but in pract- 
fee its use is rather restricted, since detailed knowledge of the working of the disk 
units ls not widespread. Additionally, the different ROMs are largely incompatible, 30 
that general-purpose machine-code is made more difficult to write. And there is not & 
great deal of RAM. Each 'M-W’ command ean write 34 bytes at most. 


Syntax: PRINT#15 followed by a character string of this form: 
M - W start addresa (low byte} start address {high byte) number of bytes dats. 
For example, the following formats are accepted: 

I$="w- A" + CHAS(O) + CHASCLE) + CRR9(1) + CHAS(O): PRINT#IS, XS 

PRINT#15, “W-R“CHR$ (18) CHAS (0 CHAS (1) CHR9 {1} 
where the first puts a null byte into $1006, and the second puts CHRS(1) into the 
zero-page location $12. (This in fuct represents a drive number}, Like M-R, this 
command has no expanded form. 


Exampies: The first example converta an 4050 disk unit number (nto a new value, bY 
poking two zeto-page locationa. Typically, this {s used to copy from a 4040 drive to 
an 9050, Dy DLOAD “BASIC PROG’,D1,U@: DHSAVE "BASIC PROG", DO, Ud and other similar ~ 


commands . 
PRINT#LS, "M-8CHRS (12) CHRS(O)CHRS (2 CHRS (9+ 32) CHAS (H +64) :REM NEEDN'T BE 2. 


The next example Is more complleated, it shows how machine-code cin be stored in the 
dink buffers, Suffer number 2 is used (0 and 1 are used by DOS) and the cade \4 
executed by the internal (not [FERE) procenaor, which pecks 16 bytes from that proce 
ennor's addresanbie memory, The result ta Ktored In the RAM snared between both 
Processors, !t occurs in ‘DISK MEMORY DISPLAY’ by dim Gutterfleld. 

L110 DATA 77,48,87,0,18,16,162,0,180 — :REM MACHINE-CODK BEFORE THE ADDRES... 

420 DATA 157, 04,6,292, 224, 16,208, 245,108,252,250 - Ame ,.. AND AFTER 

130 FOR J = 1 TO 9: RKAD X: CH o CB + CHAS{X): NEXT 

$40 FOR J © 1 TO L1:AKAD X: DY « DF + CHHSCKI: NEXT 

318 ACM UeLOW BYTE, VoHIGH BYTE, OF DISK PROCESNOR LOCATION TO BK PERKED 

920 PRINT#1G, C9; CHRS(U);CHAG(Y) ;DF ;AEM CODE NOW I PLACE 
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The string C$ contains M-W followed by 0 and #812, which is address $1200 stored 
with its bytes in reverse order. The next byte is 16 decimal; this is the number of 
bytes to be written to memory, The data statements have only 14 further bytes; the 
remaining two are supplied in program-line 320 by CHRS(U}) CHRS(V). The effect of 
the code is as follows: 

$1200 LDX #$90 

$1202 LDA ADDRESS ,= 

$1203 STA $0640,1 

$1208 Nx 

$1209 CPX #3510 

$1208 BNE $1202 

$120D INP ($FFFC) and this can be checked by fooking at the decimal equival- 
ents of the hexadecimal tisting. This routine can also be written into a BASIC disass-~ 
embler, so the workings of the disk processor can be examined. 


M-E 
MEMORY-EXECUTE 


Jumps to the specified location in the IEEE processor's address space, and executes 
the code it finds there. This may be a standard ROM routine, or user-written code 
which has been stored in RAM with M-W. ROM routines can be found by disassembling 
DOS or by reading other peoples‘ programs. 


Syntax: M-£ has only two parameters, the low and high bytes of the execute location. 


" PRINT #15, "M-E" CHR$(231) CHR4$(211) is a typical example. There is no alternative 


expanded form of M-E. 


Examples: This command calls the hardware reset address in DOS: 
PRINT#1LS, "M-W" CHRS(O) CHRS$(18) CBR$(3) CHRS{108) CHA$(252) CHR$(255) 
PRINT#15, "M-5" CHA$(G) CHR$(18) : REM PERFORMS INDIRECT JUWP TO ($FFFC) 
Ag we shall see this is equivalent to PRINT#15, "UJ". 


a ecror LED and DSS are operated by a routine at $0925 (4040) and SEEB3 (8050). 
PRINT#LS, “M-E" CHR$(179} CHR$(238) +REM PROCESS DS$ FOR 8050 


thi routine in the directory processing which computes the total number of blocks free 
ast caaot a eter een in the appropriate position in the directory. ts at 
an 27 (8050). So again a routi ik i 

BRO ce oi tee cabro@ine: £ tine like the following may be used from 

PRINT#15,"R-B° CHA$(231} CHR${(211) 
Thla may be followed by the routine in M-R te print the directory, which should be 
updated to reflect the correct total of free blocks. 

The memory-execute command ieads naturally to the last (documented) special 
DOS commands, of which there are 10, all beginning 'U'. and referred to ag user~- 
commands or user-defined canmands. Their function [gs exactly the eume as M-E, except 
that no address is specified; it ls implicit instead in the command, For example, 


PRINT#15,"U3" and PRIAT#16, "M-E’ CHRS(O) CHRS$(19) 


are Identical in thelr effects; each fumpa to $1506 In DOS RAM and executes whatever 
i fas been written there. As the table indicates, each address Is separated from 
ta pelehbens by three bytes, so the intcntlon Je to use the commands wilh a Jump 
ale - a.g. $1300 JMP (FFFC) / $1303 JMP SEEBI/ $1308 JMP $1200 and so on. As 
hw seen atready, Ul and U2 ere exceptional - they ore used in pinco of H-R and 
bets: and have channel, drive, track and aector parameters in their command atrings. 
aan that some of the jump addressea, in the carly disk drives, are to non existent 
ae regars in expansion ROM. This is an error, since these addreguea, if required, can 
wine a be acconned from tho RAM jump table, e.g. oy $1309 JM# $008, which kneps 
jen optlons open. Later disk units have a uniform jump table in the third buffer, 
fare because tho eartleat buffer which fan‘t allocated hy DOS, that fram $1200- 
igdiec. fa a popular focation for machine cede ruutines. Obviously, considerable know- 
9 of machine-cods, and of the workings of CHM disk unlta, ts neceasury to usa 
eae commands fruitfully, Some commercial software, for example, has neveral routines 


af 4 
aed: to read and write sectors in non-standard ways to diak, an a security 
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UA - UJ 


User-defined jump addresses + NMI and KESET vectors. 
COMMAND FUNCTION 


Ut or VA B-R (BLOCK-READ) 
8-W (BLOCK-WRITE) 


U2 or UB 
JUMP _ADDRESS TABLE 


2000/3040 4040/8050 
$1300 


$1300 
$1303 


$1303 

$1306 $1306 

$008 $4309 
$130C 


$D00B 
$130F 


$D0cE 
$10F0 (=NMI) 


§D0b5 
Power-on Power-on 

























Notes on direct-access programming The memory-map of CBM disk units is made more 
complicated by the presence of two processors, a 6902 which handles the IEEE comm- 
ands, and a 6504 to control the disk. These have RAM in common, as might be expect- 
ed, consisting of 4K in total, or 16 'pages' of 256 bytes. Most of these are buffers for 
input and ontput to the disk: several hold BAMs and directory information, although, 
because of the varying storage capacities between the units, the number and arrange- 
ment of these buffers differs. This diagram showa the main features of the memory 
map, inctuding the differentiy-numbered RAM as between the two processora. Note the 
way that the same RAM shows itself differently to each of the processors; if you 
refer ta the example machine-cude under M-W, you'll see that 16 bytes of the disk 
processor's ROM or RAM are put into $640 and the following locations. The memory-map 
shows that $1200, from the disk processer's point of view, is $600, so that the piece 
of code and the trensferred bytes both occupy the same buffer of $1200-$L2FF or $600- 
$6FF depending on the processor. 


--~-commoan--- Disk processor 
---RAM--- (6504) 
$0200 PIAs 


$0000 Zero-page 
$0200 PIAs 
a: ./:) a 
0400 Read buffer 
i; oR burt 
MU. : ne 
LA ae 


[0007 § & W butter c 1000 BAk/directory 
Huser 
ANT tet 7 a 
20ny ~~ 
= $236" : 
ge 


AMG 









IEEE processor 
(6502) 


$0000 Zaro-pazge 

























Mann 
am directory 
4 





Thia dingram js adupted from some comments by Jim Buttorfictd an the early disk ualts. 
lt la not Intended ta ve to a detailed map, but to give the ygunerai layout of tha ay ste 
It ia not to acale. 
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The IEEE processor, as we've scen (sce M+R), can have Its accessible memory disass- 
embled very easily; the easiest method is to patch a BASIC disassembler and take a 
hard-copy printout. When exploring RAM, a test program can be used to poke and 
read back memory tocations; if the new value is retained. the location must be RAM. 
This is thorough. but painfully slow in BASIC, The Disk processor {sg less accessible, 
and requires knowledge of the working of the read buffer to extract the information. 
{It is, of course, also possible to disassemble ROM by taking the chip from its socket 
and using alternative hardware). The key to this is location $1004 (50464 to the disk 
Processor itself). If this location has its high bit set, the disk processor goes inte 
action, either reading/ writing the disk or executing code. When the location is reset 
the 1EEE part of the operation knows the operation ig over, and collects its results 
from RAM or performs the next operation. The foltowing short piece of BASIC, insert- 
ed into the routine in M-R, causes BASIC to disassemble the internal, disk, machine 
cude. 

10004 PRINT#LS,CS;CHRS(QQ - INT (QQ/258) *256) ; CHR$(QQ/256) ; DS 

10006 PRINT#LS, "W-¥"; CHRS(4}CHRS (16) CHR$(1)CHRS$ (224) oe 

10008 PRINT#L5, "M-R"; CHR$(4)CHA$(16): GET#15,QQ$: IF QQ$=CHR$(224) GOTG 10008 

10009 QQ = 4672 


Where C$ and DS are the machine-code stringa in M-W (q.v.). Line 10004 puts the 
machine-code routine into the common RAM: Line 10006 pokes 224 into $1004; line 
10008 waits until that location indicates that the routine has been executed. The 
resulting bytes are deposited in $640ff of the disk processor's RAM; this is the same 
49 $1240 ff or the IEEE processor. Hence line 10009 sets address $1240 (=4672) and 


’ peeks it using the ordinary M-R command. One character only ts taken from the buffer 


80 the code in C$ and DB$ is over-complicated far this routine. Unfortunately, because . 
of ROM variations, this routine mayn't operate without some changes: the 2040 unit 

for instance uses JMP $FECi in place of JMP (FFFC) at the end of DS, i.e. the data 
Statements end ...,76,193,254. At the time of writing | don't have a compicte list of 
corresponding addresses for all disk ROMs. 


We've seen, in M-R. how to find the duffers which contain the BAMs. Some of 
RAM is mappable as it is with BASIC ROM and RAM; for example location $0282 cont- 
rola the LEDs on the disk units, bits 3,4, and 5 determining whether drive 0/ drive lL 
/ central LEDs are fit. $12 holds the drive number, $2B the track, and so on, 


Utilities Some disk utilities are obtainable; most of them are rather disappointing. 
Instead of, say, general-purpose disk de-corrupters or index sequential files, they 
tend to perform comparatively trivi#l operations like reading disks’ i.d.s or changing 
Names of disks. As an example of the kind of thing that could be done, there is a 
BASIC routine in Compute! (Mar.'81) by D L Cone, printed in that journat's rather 
Peculiar typographic style, which has several CBM disk recovery routines, usuble even 
if the directory hag been erased, relying on the track and sector links. Other maga- 
zines (e.g. Liverpool Software Gazette) have had similar things. Track and sector 
Toutines which Interpret what they find aren't hard to write. Routines to find unread- 
able sectors, and rewrite them so ag to de-corrupt a disk, are possible, and can be 
useful if for example a diskette won't initialise. There are considerable possibilities 
along these lines; at the most advanced, rqutines to report the format of non-standard 
dlaka could be valuable. 

There are a number of utilities designed to facilltute operations which ought to 
be automatic with the aystem, but whlch have residue] bugs or problems, or are simply 
fot vury easy to carry out. The progroms 'COPY ALL' and 'COPY/ALL' for instance, * 
Available from user groups and same Commodore denlers, are intended as convenient 
nlteruatives to BASIC 4's COPY command. The latter $a designed for atl Mle types, In- 
cluding relative files, Aa new DOS ROMs are isaued, such utilltlen should become out- 
date, and there i404 chance that they may cease to work with different configurations, 

The comparatively autonomous ‘intelligence’ of theae untts should be borne in 
Mind, For example, with several different diak units connected to the anme computer, 
fopying between units becomes falrly stealghtforwacd; the unite are rgconfivured by 
foltwire xo that their unlt numbers ace different (see M-W for an 4050 exsunple), so 
transfor of programs between disks, fullowed by backups within the units, can be 
Performed, Tha disk drives can be disconnecter| while a backup ia taking place, 
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6.6 Machine-code programming with CBM disk drives” 


Files: opening, reading, and closing Let's start with a fairty simple example, which 
reads sequential files and displays the result by poking it into the screen. 

Suppose drive 0 has a sequential file called ‘DATA’ on its diskette. 

After OPEN 2,8,3,"0:DATA,S" logical file #2 is open for reading. (Different 
numbers for the logical file and secondary address have been chosen to make the 
muchine-code's operation clear). 


6; Disk drives 


$o24c LDX #$02 ;LOGICAL FILE NUMBER 
30285 JSR $?FCK ;SET INPUT DEVICE - ANY BASIC ROM 
$0291 LDY #300 
$0293 Li JSA $FFCF ;GET CHARACTER FROM DISK - ANY BASIC ROM 
$0206 STA $9000,¥;POKE CHARACTER TO SCREEN TOP 
30290 Inv 
$0294 BEQ OUT 3256 CHARACTERS DISPLAYED 
go29¢ LDA $96 ;TEST STATUS BYTE (ST) 
$0295 BEG LL ;NOT END~OF-FILE 
$02A0 OUT JMP $FFCC ; RESTORE DEFAULT DEVICES 
O2gA A2 02 20 C&S FF AO 


~: 0292 00 20 CF FF 89 60 a0 Ca 

+: OQ@SA FO 04 AS 96 FO F3 4C CC 

+1 O2ZAZ FF 
SYS 652 reads and displays 256 characters from the file on the top of the screen, or 
fewer if end-of-file is found {it is signalled by ST, the contents of $96). Because the 
bytes are poked, carriage return appears aa 'm' (the l3th. letter of the alphabet). 


(1) The routine prints "FILE NOT OPEN ERROR if the file (logical file #2) isn't open. 
(2) Each SYS 652 reads and displays the following 256 characters of the file. 

(3) CLOSE 2 finally turns off the LED and deallocates the channel, 

(4) DS ig not checked. (We'll see later how thia is done}. 


Note thet on branching to OUT, Y holds the character-count; this is usually zero, and 
pokes to the screen as '@'. A holds ST. Either or both these figures can be printed 
as numerala, for example using the routine that prints 6 line-number, which can be 
found at the end of the reset sequence when it prints '31743 bytes free’ or whatever 
figure is ita RAM. [In BASIC 4, X holds the value, LDA #00/ JSR CF&I prints it in 
decimal . 

Many coametic improvements can be made to the output; [CLEAR], CHR$(147), 
tan be printed to the screen, for instance. The file may be checked for carriage ret- 
urn characters, and output one record at a time. The output routine ($FFD2) can be 
substituted for screen pokes. The stop key can be tested for, and so on.? 


Can « file be OPENed using machine-code? Obviously this must be possible, alnce BAS~ 
IC Steel operates exclusively with machine-code, This example is one way of dolng it: 


SYS 834 "0:DATA,S" with 


$O27A LDA #302 
g027C «STA 902 
$O27E LDA #303 
90280 «STA $03 
$0262 LDA #$0% 
$0284 «ATA $04 
$0240 JSR $F390 = ;CNZCK COMMAND STRING & PIT IN BUFPER (SF4F) BASIC 2) 
$0269 JSR $F563 .OPKNS PILE WITH THESE PARAMETERS ($7524 BASIC 2) 
$028C «=LDX #$02 ETC, AS ROUTING ABOVE 


This routlne now opens the filo and disptuya the first 256 characters; subsequent SYS 
calla to 852 continue to rend the file. 

,! 027A A® O02 BS D2 AB OD 85 DI 

+: 0282 Ad 08 BB D4 20 SC FO 20 

++ O@KA 83 FS 


{LOGICAL FILE NUMBER 
;HECONDARY ADDRESS 


;OKVICE NUMBER 


sequence, Programmers not familiar with 6303 cade whould skip to the next section. 
"There's «© good sxmepie, using the acreen-s¢eroil routing, by ® Davie in CCM, ¥ol.J, 5. 
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A file can be closed from BASIC using the address in FFC3 (‘CLOSE’) in association 
with a routine to fetch parameters from BASIC. Usually it is easier to avoid the input, 
aimply loading the accumulator with the logical file number and entering CLOSE 5 bytes 
further on, In BASIC 4, for example, LDA #02/ JSR SF2E2/ continue closes logical file 
#2. BASIC 4 also has DCLOSE, which closes all files without reeding file numbers, A 
slightly tedious piece of code can make CLOSE transferrable between BASICs, by corm- 
puting the indirect address of CLOSE and adding 5, aa in the following example, in 
which A is assumed to hold the file number: 


TAT SAVE FILE NUMBER 
cCLe 
LDA PFC4 
ADC #05 
STA FCL+t 
LDA FFCS 
ADC #00 
BTA FCL+2 
TYA ;MECOVER FILE NUMBER 
PCL JMP FCLOSE ;JUMF TO ADDRESS + 5 


Programs and blocks of RAM: loading and saving from machine-code As we have seen 
in the section on program files, BASIC programs and RAM dumps are held in the same 
Way on disk (and on tape), namely with the text preceded by two dytes which hold 

the load address. The ROM routines to load and save naturally use the true values of 


;LOW BYTE OF ADDRESS OF CLOSE 


;BIGH BYTE OF ADDRESS OF CLOSE 


_ these parameters, but the machine-code programmer haa the further option af putting 


in alternative addresses, so that routines may be relocated. This is not a facility that 
ig much used, but remains an interesting possibility. In BASIC 4, DLOAD checks its 
parameters before entering LOAD. We'll thus consider only LOAD ($FFD5). This is a 
BASIC keyword, and assumes a BASIC program; thia means that variables will be 
CLRed and so on. The monitor's .L command does not assume this. In fact the main 
part of LOAD is a subroutine used by both these commands, at $F322 (BASIC 2) or 
$F356 (BASIC 4). To use this routine, tne following parameters must be correctly get; 
the named file will load in the normal place, but no pointers will be reset. 


$D1 holde length of filename 

{$DA) pointe to start of filename (e.g. to ‘DATA’ or 'F1’ or 'PRG*' io RAM) 
$04 holds dovice number - usually #8 

$9D holds 0. Thie is the LOAD/ VERIFY flag; 1 means verify 

$96 holds ©. This it# the status byte (ST), 


After these pretiminarices, LOAD‘s subroutine {s called. ST can be used to test for a 
Buccessful load; both ROM loads AND ST with #$10 to test for o load error; the dit 
should be low, so ST AND #$10 <> 0 signals an error. 

In order to load a block of data held as a program file to any part of memory, it 
la only necessary to simutate that part of LOAD which fetches the 2-byte load address 
from the fille. Supposing that the {lst of parameters above has been set, we need: 


LDA #60 

STA D3 ; SECONDARY ADDRESS O 

JGR F4AS ;SENO MAMK TO IEEE, (F496 IN BASIC 2) 

JER FOD2 i8END ‘TALK’. C(FOB6 IN BASIC 2) 

LoA 03 

JER F199 {SEND SECONDARY ADDRES (F128 IN BASIC 2) 

I5% FCO ;GET LOW BYTE OF ADDRESS {F18C IN BASIC 2) 

LDA $945 }CHECK ST'S BYTE 1, 1.8. 2ND FROM RIGHT 

LAR A 

LEA A 

BCC CONT ,8T OK 

JMP FXC1 ,ABGRT PILES, PRINT ?FILE NOT FOUND ERROR (P568 IN BASIC 2) 
CONT yar FICO j;GET HIGH BYTE OF ADDRESH. BOTH BYTES ARZ IGNORED. 

JSR F392 REJOIN LOAD (PITHOUT PRINTING "LOADING ...'), (#335 TM BAXIC 2) 


The named file wii now be lowded from ($FB) onward In memory. Thla address Is 


Rorpmaily sut from tha two bytes which ore thrown away by the maching-coce routine, 


Se the contents of $F and $FC must also be set by the introductory rautines. 
The cody may be treated ag a subroutine fe.g. fallawed by HTS) or used in-line, 


. 
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SAVE‘s address in the kernel jump table is FFD. It's construction is similar to LOAD, 
but ersier to follow, since the BASIC version doesn't require to be processed, as it 
ja after LOAD. Ita general layout is: 


§1 JSR GETPAR; GETS NAME, LENGTH OF NAME, DEVICE, SEC. ADDRESS FROM BASIC 
&2 JSR STTEND; SETS (C9) AND (FB) TO END OF AASIC / START OF BASIC 
$3 LDA D4 } CHECKS DSVICR NUMBER, AND BRANCHES ACCORDINGLY; 


IBEE SAVE ~ THIS INCLUDES CBM DISKS 
3 CASSETTE TAPE SAVE 


The subroutine at entry-poirtt Sl fetches the same parameters as LOAD, and sets the 
same default values, with the exception of $9D, the load/verify flag, which it ignores. 
The subroutine at S2 simply stores the start of BASIC pointer in (FB) and the end of 
BASIC pointer in (C9). Obviously, the monitor routine .S "0: HELLO”,08,1234, 2345 
bypasses thesé, storing its name pointers and address pointers in the appropriate 
focations, and going straight to S3. It is, in fact, acceptable to enter this routine a 
Mttie later if the parameters are correctly set, since there's no point in comparing the 
device number with #3. Once again, we can modify SAVE if we choose, For example. 
instead of sending the toad address as the first two bytes, we might send the horiz- 
ontal and vertical sereen positions at which to load the dats; or we might not send any 
leading values; or we could send an extra code byte with some meaning of our own. 
In each case, there must be a corresponding LOAD routine to process our non-stand- 
ard program file. The IEEE SAVE's major portion can be simulated like this: 


UDA #61 

STA D3 

JSR F4AS ;SEND NAHB TO BUS (F466 IN BASIC 2) 

JSR FODS ;SEND 'LISTEN' {FOBA EN BASIC 2) 

LDA DI 

JSR F143 ;S8END SECONDARY ADDHESS (F128 IN BASIC 2} 
LOOP LDA ?? 

JSR FASE ;SEND A CHARACTER TO THE FILE.. 

B?7 LOOP ;..IN SOME SORT OF LOOP 
END BIT D3 

BMI RET ;BRANCH TO RTS 

FSR FOODS ; SEND ‘LISTEN’ (FOBA IN BASIC 2) 

LDA 03 

AMD #EF ‘ 

ORA #E0 

JSR F143 ;SEND SECONDARY ADDRESS {F128 EN BASIC 2) 

UMP F1B9) «=;SEND 'UNLIATEN* (F183 IN BASIC 2) 


The piece of code at LOOP sends the data from the accumulator, The ROM save, of 
course, Cirst senda two address bytea, then consecutive bytes in ascending order 
from the low to the high address. It. is preceded, in effect, by code which sets ihe 
length of the name and its pointer, the device number, and ST+0. The secondary 46- 
dress Is not needed; the routine scts it to t fur write. 

Aa the entries In SAVE und DSAVE (Chapters 5 and 7 respectively) show, it's 
possible to modify SAVE even from BASIC, by poking new 'sturt' and ‘end’ adresses: 
BASIC followed by machine-code (¢.g. Supermon) can be saved ag a BASIC program 
by raining the end-of ASIC pointer to include the machine-code, A screen display can 
be saved as a program file by temporarily changing the sturt-of-BASIC to $4900 and 
the end-of-BASIC to $8400 or $8460. for a 4C-column and 0-column screen renpeutively- 


Sending a command string to a disk drivma  (sually the command Ktring dy put inte the 
laput buffer, and sent fre there to the dink drive. it la nut however nacesury “that 
n string be held in a buffer; it can be incorporated Inte ao machine-code routine or 
subroutine, The sequence of operations is this: 


(lL) Put #8 Into $D4 aud 4#GF {nto $08 (device number 8 and pce. addrenw 25), 

CH) Send 'Blsten'. 

CUE) Sond the seconilary address. 

tiv) Send the command string sequentially. Uf the string Is held In the input 
buffer, a zero byte will terminate Jt; thin sbheukd not be Kunt, 

(¥) Send ‘Unllsten’, Tho dick aperation will take placa tow. 


™ 
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Command strings are sent to the disk drive in the older form of disk syntax, which 
the newer BASIC 4 commands (DLOAD etc.) olso use, sending exactly the same strings 
after checking their newer syntax. The retative file handling is accomplished in the 
same sort of way, but the strings it sends are not recognised by DOS I+. For a summ- 
ary of these commands, see Chapter 15's tables of BAS(C ROM; BASIC 4 from D833 
lists the format of the commands, including the .L construction which opens a new 
relative file, and the P construction for RECORD (sce DASL). These commands permit 
relative files to be read and written from machine-code, 

As an example, suppose the input buffer is used to take in the command; this 
means that the cursor will flash in the usual way, and characters will eppear on the 
screen as they are entered ot the keyboard. Carriage return terminates the input, and 
in fact puts a zero terminal byte as a marker at the end of the string, which is moved 
to $0200ff. This program sends a command input in this way to disk: 


ISR ; INPUT TO BUFFER (C46¥ IN BASIC 2} 
LDA 
STA 
LDA 
STA 
JSR 
LDA 
JSR 
LOX 
LBA 
BEQ 
JSR 
INX 
BNE LOOP 

JSR P1LBe 

CONTINUE ... 


For example, $1 sent by this code disptays the directory of drive 1, and 01-0 performs 
@ backup of drive 0 onto drive 1, S0:PROG* scratches files on drive 0 which begin 
PROG, And so on. 


BAE4 
#08 
Da 
*oF 
os. 
FODS 
Da 
F143 
#00 


;SEND 'LISTEN’ ({FOBA IN BASIC 2) 


;SEND SECONDARY ADDRESS OF 15 (F128 IN BASIC 2) 
;SEND BUPFER CHARACTER {(Fi6F IN BASIC 2) 


ALWAYS BRANCHES 
‘UNLISTEN' {¥183 IN BASIC 2) 


sTHIS 


<ND ; SEND 


Disk status messages (DS$ and DS) These are easier in BASIC 4 than earticr BASICS 
because routines exist which recognise DS and DS%. For example, 

JSR C024 fetches DS and puts it in floating-point accumulator #1. 

JSR BFC sets up the DS$ string in BASIC RAM, and sets the length parameter 
in $0D and the pointer to its start in ($0E), so that, for example: 


JSR BFCS ;GET DS$ (BASTC 4 ONLY) AND S&T UP STAING 
;SET HORIZ. AND VERT. SCREEN PARAMS, IF NECESSARY (SEE HTAB, VTAB) 

LDY #FF 

Woop imy 

CPY $0D ;COMPARZ OFFSET WITH LENGTH OF STRING 

BEQ EXIT 7AND EXET WHEN EQUAL 

LDA (908),¥% ;LOAD CHARACTER FROM GTRING 

JSR FFD2Z ;STANDAHD ROUTINE TO OUTPUT A CHARACTZR 

SNE LOOP {BRANCH ALWAYS (ACCUMULATOR LOADED WITH NON ZERO CHARACTER) 


EXIT CONTIAUE... 


DS$ can be texted at any tlme without printing the string by this sort of routine, used 
by HEADER to declde whether the newly-formatted disk waa a ‘bad disk’ or not; 


J9R DOOL .GET DS% (BASIC 4 ONLY) 
Lpy #90 

LDA (0£),¥ 

cup #32 

BCa EAROR 

CONTINUE... 


The rationale in that DSS mansages starting with 2 or more moy be serloua, while thon 
with Dor 1, doo. OL, 10,11,12,...,19 are not, In practice a number of meqsagea 

Are warnings rather than errors, The enalest way to teat for messages which are not 

to be conaldared ‘fatnl! In provably to fetch DS an @ floating-point number, cunvert It 
to an Integer with a ROM routine, than test the low byte of the resulllng integer. 


. 
“ 


~ ein, 2 
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BASIC<4 can read the error channel, and display DSS, using this routine: 


LDA #8 
STA D4 , DEVICE NUMBER 
JSR FOD3 ;SEND "TALE* 
LDA #OF 
STA Ba ;SECONDARY ADDRESS 15, WITH *TALK' 
JSR F193 ;SEND SEC, ADDRESS (F164 IN BASIC 2) WITH ‘TALE’ 
LOOP JSR FICO ;GET BYTE FROM 1EEx (F18C IN BASIC 2) 
CaP #D 3 RETURN? 
BEQ OUT ; TF SO, GO OUT 
JSR £202 ; PRINT TO SCREEN - CAN USE FFDZ POR OTHER DEVICES. (£308 IN BASIC 2) 


BNE LOOP ;BRANCH ALWAYS AS ACCUMULATOR DOESN'T HOLD NULL 

OUT JSR K202 ; PRINT FINAL C. RETURN (E3D8 IN BASIC 2) 
JSK FIAE ;SEND 'UNTALK' (FL7F EN BASIC 2... SLIGHTLY DIFFERENT ROUTINE) 
CONTINUE. 


Routines like this will work with either BASIC 2 or BASIC 4, but in practice they are 
unlikely to be used with BASIC 4, since they are already built into ROM and can be 
used more eccnomically than BASIC 2 allows by a direct call, 

Throughout this section [ have not referred to BASIC 1; in fact this is usable 
with disks, but to save space I have omitted its ROM entries and other details where 
the ROM and its RAM allocation differa from later BASICs. The tables in Chapter 15 
can be used to help make these interconversions. 


(FOB6 IN BASIC 2) 


6.7 Compu /think disk drives 


General ‘Plug-compatibility’ in the world of large computers refers to peripherals such 
as disk units or printers which may be substituted for those made by the computer 
manufacturer, the aim being to save time (if delivery cates are better) or money. This 
phenomenon has spread to the microcomputer industry. The more successful makers of 
micros have found innumerable suppliers of extra software, chips, interfaces and so 
on operating from outside their companies. Sometimes ex-employees help produce the 
stuff, This puts companies like Commodore in a slightly difficult position; their res~ 
ponse is usually to encourage such alternatives unless they themselves have a@ similar 
product. Disk units are an important case in point, since they are expensive to buy 
and costly to maintain. High capacity disk units are quite a bit more expensive than 
the computers which use them. A number of non-Commodore disks have been produced 
and are sometimes met with. ‘Novapac’ disky for example were an early entrant into the 
fleld. KHobaud-Microcomputing magazine ran an article on adding $100 disks to a PET 
(R Freeman, Jan.'80). Byte can ao series {June 81 ff.) on connecting disk units, using 
disk controller chips, New units, including hard disks and even modified full-size hard 
disks, continue to be old. However. fora long time Compu/think disk drives were the 
only targe-capacity storage system for the PET and CBM, #0 a gepurale section on then 
seems justified. There are alsa many operational differencea from CBM disk units, and 
the comparison [a ofttn inutructive. Commodore literature at present scarcely mentions 
alternative disks or printers to their own. There is little published muteriai on these 
drives; Printout, and the PET Benelux Exchange magazine {in Dutch!), have run 
erticlea. 
Physical size, capacity, operating system Twin drives, typleally MPI or PERTEC, are 
mounted vertlenlly, under 4 standard three-slded sheet metal case. The appearance ia 
similar to the 4061/ 9062 drives announced by Commodore, but analler, Thta amall size 
ie achieved largely by filling the CHUM with ita eleetrunica. consisting of a main board 
holding EPROM and RAM, Thera now exist single aliled versions, singte sided double 
denaity versions, and double sided, Gouble deusity versiona, using & 1/4 Inch disks, 
with storage capacities of 2 x 100000, 2x 200 00, and 2x 490 G00 bytes respectively, 
and a further 8 Inch modol, which is largor, and stores 2x @U0 000 bytes, These ail 
operate with a disk oparaling system cnlted Diskmon, which ia compatihin only with 
BASIC<4, borause oli thr meinory from 39006 to SHEEP In oceupled by ROM and HAM 
with thia syatem, not ail of which Im free with BASIC 4. There In a furthor Compu/- 
think product called UB-DOS which occuples ROM slot 59000-9FFF. 

The operating syatem of these dinks in quite portabie; nat much Commodore ROM 
fa uaed, and even quite trivial features, auch aa the rectangular border around the 
screen are purameterised, In fact the sans ayastem le unad In # differant machine, 
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distributed in the U.K. by ACT Ltd. (‘Applied Computing Techniques').* It is not an 
IEEE system, and does not have the eutonomy of CBM drives; it ls more accessible 
and can be pecked and disassembied freely. It is initialised in the same way that tool- 
kits are, by a SYS call, in this case to $H000 {SYS 45056). This puts a wedge into 
BASIC's CHRGET routine, & widely-used technique to enhance BASIC - sce Chapter 
14. The function of the wedge is to check for the ‘$’ symbol and interpret subsequent 
characters in its own way. Only the initial of the subsequent command counts; any 
following characters are ignored,’ unless they are either a comma, semi-colon, ‘or end 
of statement byte. This of course is fairly standard, The operating system shares many 
of the cassette tape system's locations; the zero page is a little overcrowded, so for 
example random numbers don't work correctly with the disk drives in operation. The 
usual aimple Stop-key disable prevents the disk system from working. Two commands 
are designed for use with printers connected via the user port (not IEEE) and cables 
equipped with Compu/think's own interface; this presumably is an RS232 connection. 

The format and organisation of the disks is far simpler than Commodore's, which 
must help expluin its earlier arrival on the scene. The general system is less ambitious 
and appears to have fewer obscure bugs as a result of this. On the other hand, it has 
considerable limitations which have to be programmed around. , 

The drives have 40 tracks with 5 1/4 inch disks, 90 tracks with @ inch disks. 
Each track hag 10 sectors. Disk handling is by a Western Digital chip: single density 
drives have 256 bytes per sector, double density drives 512 bytes. The smatlest unit 
which Diskmon uses is the truck, i.e. 2560 or 5120 bytes. all of which is saved onte 
disk or read from disk. The directory is held on track zero; thus there is a maximum 
of 39 or 79 files and programs on any disk side. When a record from a file is read, 


’ the whole of this iarge buffer is filled, and a pointer used to find the actual record. 


Compared with CBM's 256 byte buffers, this is wasteful, and one of the serious limit- - 
ations of this system is that only one file can be open at a time. For some purposes, 
for example adding to a file which is partiy complete, this is fine. But it makes ordin- 
ary file updating difficult. The buffer may be updated by poking data in: since 
the Position of this buffer {normally $9000-$AJFF) is known, this is a practical prop- 
osition, as we shall see. But it is not convenient. it is one reason why software using 
these drives tends to be slow, if it isn't well written: a file is repeatedly opencd and 
pod: alternately with another (updated) file. As we shall also see, tracks can be 
weaee and saved into non-standard buffers, notably the top of RAM after the memory 
Legon been lowered by poking. This can be a powerful technique. One buffer can 
pies a index, the other data, 50 an indexed sequential system may be implemented 
si out too much troubie. There is an exception to the rule that tracks are the lowest 
rege Reneapal ry of the system. Program files, which include machine-code dumps like 
: disks and tapes, are saved, from the starting address, in whole sectors. As long 
me programmer knows this, it causes little difficulty. But it makes overlays more 
ficult, because RAM which is further up memory than the theoretical end of a pro- 
gram or machine-code routine is overwritten. For example, machine-code saved in the 
Pichia buffers ($027A - $SO3FF is untouched by Diskmon} will, when foaded, reach 
it . $0Z7A - $0479 If the system ia doubte-density, and If the code started at $027A. 
pina therefare be joaded by a BASIC program unless another program is loaded 
a once to relnstate BASIC in $0400 and the aubsequent locations. Similarly, code 
pf . type of Supermon or Extroamon, stored at the top of memory, and snved to disk, 
rid nts the top of the acreen as It was when the code was saved, because screen RAM 
adjacent to the machine-code, and some of It is stored with the code. 
P iter or are differences In style between these and CBM disks, which are naa much 
shoe of taste as anything elsc. Those diska aave with replace without comment, 
ne BM disks print "file exinta error. Files aro erased ('acratched') without comm- 
wines trrora are reported with an crror number aad treck and sector number, and the 
Li pla) urashea fl.e, atops, printing "READY .‘), There is no error measige; the man- 
aan pe a vague indication of whit the arrorn (an returned by the disk controllar) 
eet BM'a DS and DS em menna that this need never happen, Decaure an orror 
is i woe eee Stet Sen 














@n example of the paramsterisetion, try this demonstration routine (HASIC 2) which 


‘1 0334 49°00 AD 60 AZ GN 4C GH repetitively prints different ructangler tu the 
a screen, using the machine-code subrautine: 
FOR Je 0 TO 40; POKE 627,6: K : 
NEXT: Cord 6 t 4(Kel) AND 253: POME §a9,J¢.6; POKE 431,J: SYS 826: 
ce story by Gerry Setaherg telts of the consternation he aroused in an enthusiast 
“ea: he off his typing-error-resistant aystem, dy innocently typing aceathing like 
KTK'. It fe possidie, but uniskely, that $F in place of 9D wtii erase a Ules. 


+ 0342 BE 





Progronming the PET/C&M ~200- 6: Disk drives 


can always be detected with DS, and an appropriate request for action issued, 
e.g. ‘Please put a disk in drive 9'. 


Commands The tnbie tists Diskmon's additional commands with CBM equivalents. To 
simplify matters i've assumed drive 1 with Compu/think, drive 0 with CBM, although 
ranges of 1- 4 and 0-1 respectively are normally valid. Most conversions should be 
fuirly easy, but there are likely to be problems if multiple files are open with CBM 
disks, since Compu/think can’t handle this situation. APPEND and some other com- 
mands are hard to translate into Compu/think usage. A few complications are omitted. 


Compu /think CBM BASIC <4 


SF,1 [No title or i.d. is PRINT#15, "NO: TITLE, ld” 
assigned by SFORMAT ] 
$D,1 

$5, 1,"PROCRAM" 






CBM BASIC 4 

















HEADER *TITLE”*,O0, lid 































DIRECTORY D0 PRINT#15, "$0" 

DSAVE "PROGRAM",DO SAVE "0:PROGRAM", 8 
$5,1, "M/CODE*, "1234", "2345" -S,"0:M/CODE™*, 08, 1234, 2365 
$L,1,"PROG* DLOAD "PROG",DO | LOAD "0:PROG",B 


$L;1,"PROG" {Loads without affecting the running of the current program, unlesa 
it is overwritten. There is no easy CBM alternative]. 


$X,1, "PROG" [DLOAD then RUN |LOAD then RUN 

{Londs and executes BASIC or machine-code. The first command with Compu/think 
should be CLR. Similar CBM instructions include DOS suppart's up-srrow function, 
the shift-stop key, and DLOAD or LOAD in program mode only }. 


$X;1, "PROG" {Loads a new BASIC program and rung it, retaining previous variables’ 
values, subject to the provisos on program length which also apply to CBM programs 
loaded from program-mode. Because of Compu/think's sector-louding principle, the 
new program must be sufficiently short that its final sector doesn't overlap the end- 
of-program pointers, and thus corrupt the stored variables]. 


$E,1,"FiLE" SCRATCH “FILE”,DO PRINT#t5,"S0:FILE® 
DATA FILE HANDLING: 


Opening a new fila: 
$0,1, "0", "FILE", "PARAMS" DOPEN#1,06, "FILE", W OPEN 1,8, 8,"0:FILE,S,W" 
or: |DOPENH,DO,"FILE”,L50 |OPEN 1,8,8,"0:FILE,L%+L3 
[Note that $0 has the same torm with sequential and relative (or ‘direct access’) files. 
This trick Is done by storing parameters in the directory entry, for use (with sequen” 
tial files} as a store of (say) creation date, but, since this can be written as a record 
anyway, this is less important than its random access interpretation. Ita eight oytes. 
for example [$:CHR $f 7) *CHRS(3}+*CHRS(55)*CHRS(1)*"XXXX", define the number of 
records in the complete file, followed by the record length; the rest is ignored. So 
the example allocntes 311 records of length 264. The directory keeps 4 record of the 
tracks allocated to a file; records fil trucks and straddle over ta the next track J. 







Opening o file which exists already: 

50,1, "W", “SEQ FILE", "PARAMS"| DOPEN#I, DO, "SEQ FILE", W| OPEN t,6,8,"0:5EQ,5,¥" 
$O,1,"R", "SEQ FILE",15 OOPEN#,D0,"SEQ FILE” | OPEN 1,3,8,"6:SEQ FILE" 
$0,1,"D",*REL FILE*.1$ DOPENS),D0,"REL FILE" ; OPEN ?,4,8,"@:REL FILE” 
[Theae are, In order: (1) Sequential file opened for writing, dh) Sequential fhe opert- 
ed for reading, (ily Direct access fila opened fur both reading and writing]. 


Reading recorda frum/ writing records to / filvs of gequentind and dirnet necess type: 


$R,R$ INPUT HT. RS {INPUTHE, RS 
SRINLRS RECORDA1,(N): INPUTEI,RS see RECORDS (Chap. 7} 
ow, R$ PRINTAT, RS | PRINT#1,R$ 
SW;N RS RECORDS1,(N): PRINT#I,R$ see RECORDS (Chap. 7} 
Cloaing a file: 


K 




















DCLOSEN CLOSE t 
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Compu/think DOS has five further commands which don't appear in CBM BASIC, and 
several other features. 


$Band$P ('BLIST' and 'PRINT') operate only with printers connected to the user 
port (not the IEFEport}. $B,"NAME" prints a heading, page numbers, and a listing of 
BASIC with 50 lines to the page. It does not attempt to print screen editing characters 
in a readable form. $P prints a line, as PRINT# does to an IEEE port printer. 


%& is intended for use with machine-code; after loading it, $6 isa intended to 
execute it, since the load address of the code is known. The effect should be identical 
to a SYS cali to the first Iecation of the code. However, this command has a bug! The 
relevant code is: 


BS3D LDA #4C ; JUMP OPCODR (BASIC 2 VERSION) 
STA 27 ; LOCATION PRIOR TO START ADDRESS 
JSR 0028; SHOULD BE 0027 


With BASIC toaded, the jump goes to $28-$29, hoiding pointer {iow - high) to start of 
BASIC, and to $2A-$28, holding the pointer (low-high) to the end of BASIC. So if 
BASIC is loaded, the code encountered is 


9028 ORA (04,Z) 
QOZA -VARIES WITH END-OF-BASIC- 


So, for example, if the program's length is varied so that PEEK(42)=96, $G will simply 
return and print READY. , because RTS has decimal value 96. When trying to run 
machine-code, the effect depends on the load address of the code, and is far more 
variable; usually it will crash. 


$H clears the memory ('HALT’), having a similar effect to a power-on reset, ex- 
ipa that locations below BASIC aren't affected. In this way the wedge to the system 
is retained. 


$M is a memory-displaying command; $,"1234 displays 190 bytes, in hex and in 
ASCIL equivalent. It is rather slow in action; a fast-screen poke may be desirable. 
(See Chapter 5, PRINT). The following (completely relocatable) routines supplement 
this command: > and < step forward and backward to the adjacent section of memory. 
] and [ jump about 1K, so the routine can be used to scan memory: 


BASIC 1 BASIC 2 

O33A 20 FT? BOS CB 3E FO F9 CO -: 03394 20 OD BA C9 3E FO F8 C9 

0342 3C FO O09 CB 3D PO 14 C9 -: 0342 3C Fo 09 C9 SD FO 14 C9 
+t Q34A 38 FO 1A 60 18 C& F& AS -: O34A SB FO 1A 60 18 CH FC AS 
+: 6352 FT 69 84 8S 77 BO £1 Ce -: 03952 FB 69 84 85 FB BO El C6 
: 354 F8 90 DD AS FR 69 OF 18 -: Q35A FC 90 DD AS FC 69 OF 18 

0342 85 ré 16 80 D3 AS Fa 69 -! 0362 83 FC 18 90 D3 AS FC 69 

O34A ER 85 FB 18 BO CA -: QO36A EE 85 FC 18 90 CA 


The EPROM contsins a sertal number, Identical to that on the disk drive, There 
{a a security location, Thts is made possible by the use of the wedge. !f you trace 
the jump address In $8900, you'l} find the initialisation routine for the wedge, which 
Given the address to which CHROET will now jump - e.g. B43E. The routine stucting 
from here first saves the processor status and other things; the next operation is to 
Check $C40A (-1034) for the presence of #24, which Ja usually an asterisk. * (lt may 
hot be; the following examples happen to include #2A in ihe link address or Inenumber 
40 If either format is accidentally used, the protection wlll unexpectedly coma into 


Play: 
y 10 REMX 
42 REM ANYTHING. The firet line must be 2 tokens long; thu second hes line 42, 


3 REMABC 
10 REM THIS LINE MUST COMTAIN 27 TOKEME EXACTLY) 


If #24 in detected. only %i, Sil, or RUN ara uauble. $f erases BASIC; $i, an we've 
oar is table to crash, but thia cam be prevented by manipulating the pragram lergth 
ine pecking lneation 42. Thus, only RUN Is left. This is Compu/think's equivalent of 

af Auto-pun meallficationa of the CHM ta HASIC, [bt prevents LIST anil ela prevents. 
rial da deletion of program lines by uxers entering Aumbeers, We shalt sce how to : 

"Wert lhe charactee in the seetion aa receding tracks and using tha dlreetary. 


Sums old versione use PORE 4,160 ae their security Jocation. 


5 « 
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Bugs In Diskmon ‘The manuals record several types of bug; these chiefly relate to 
string handling of the parameters used in file handling. For example, in this situation 


100 $0,0,"R","SiQ FILE", I$ 
120 $R,RS 


a sequential file ls opened for read, and a record (R$) is read. I$ should now take 
the vaiuc assigned to [$ when the file was originally written, and R$ should be the 
record ag it was wrilten to the disk file. fn practice, either of these can go wrong: 
the best preventative is to assign the variables twice: 


QO If=""; Rg" 
122 RS=kS+"" 


These program lines correct the deficiencies which may exist. 

Further bugs include the introduction of spurious characters at the end of long 
program lines, the failure of integer variable (e.g. X%) prrameters to operate correct- 
ly, and the well-known IF probiem. requiring the use of the short IF statement, 


IF 031 THEN $D,2 
1¥ D=1 THEN: $D,1 


becauge the first version always performs $D,1 whether or not D=1. This is a problem 
with many wedge programs; provided it's remembered, it causes no problems. Some- 
times the disk drives are left spinning after an error, perheps a failure to find a file. 
The validation is not very thorough with these disk units. They can be stopped by 4 
SYS call to the motor-off subroutine. or, more easily, by calling a directory with $D.0 
or SP,1 ete. after which the drives stop. 


Jump table of Diskmon functions and RAM and ROM memory map 


Baod 
6003 
B06 
6009 
Bocc 
Boor 
Bo12 
BOIS 
Bois 
801B 
BOIE 
8021 

Bo24 
8027 
Bo2A 
Bo2D 
B30 
6033 
Bo36 
B039 


aust be replaced by 








45056 Inserts a jump command into CHRGET 

45059 Returns from CHRGET - replaces processor status and enters CHRCOT 
48062 Reads directory into a short burfer (e.g. 1K. Depends on capacity). 
45065 Motor off, may also write updated directory to track G. 

45068 Clear 25 byte blocks in directory to erase file. 

4507t Allocate track (read). 

45074 Allocate track (write}. 

45077 Erase file - if it exists - from the directory. 

95040 Write buffer from %9000-S$A3FF to disk track, (AFFB-drive, AFFF track). 
45083 Read truck into $9000-SA3FF. 

45086 Write buffer from pointers, e.g. (FB) through (C9), 
85089 Read track into area defined by fow/high pointers, e.g. 
45092 Turn motor on. 

85095 Turn motor off. 

45098 Save program to disk. 

45101 Print line witn $P ar $8 to parallel port printer, 

45104 Load program from disk. 

85107 Read directory; set relative track to zero. Then: 

45110 tncrement relutive track number, allocate track, read program truck. 
45113 ASCIi/hex. {Ff X<> 0, A becomes hex of X & Y; if X=0, X & ¥ become ASC(A) 
BOIC 45116 Perform $X (lond program and run it). 

BO3F 45119 Continue with SAVE. 


Some of these routines are usable from BASIC, This ls not an exhauatlya liat of jump 
locatlons; thoxe corresponding to $ commands - $R,$C.$D, and the rest ~ vary with 
versions, but can all be found after the inftiatisxation reiting to which O00 fumps, [n 
BASIC2 (where peeking 19057243) the comparisons and jumps start al HAC2, BASIC i 
(with peek of 45057735) slurts at B4aNé. The pointers and sbeolute addresses of the 
buffers vary with the model; ao deod the length of buffer ullvested for the directory 
track. Tha examples quoted above apply ta BARTC 2% double density veralun of Disk- 
mon, Goneralty, iW Je not too difficult to locnie subroutines which set pelnters and aet 
absolute vniues of track limits, because they teko the form of Ionding the necumulator 
with & value/ atoring it/ louding with anuther value/ and ao on. ituvtinean like SM and 
$0 are Cairly ensy, Becatise thore'4 w batch of in Une coding, usually ner tables of 
text Lhe ‘DIRECTORY! or ‘MEMORY DUMP’, and In association with a menory-map tt 
in [rasible tu decode such routines, The most diffiedlt to understand are (hose which 
deal with flie opening, roading, writing, and cloning. 


(FB) through (C9) 


Ie TEE PE: an ae 
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Aa00-AFFF AFOO-AFFF 





Se 













3000 Aa0 


AFDO-AFD1 Block byte counter 


Screen RAM Unused RAM AFO2 Switch {1 Read, 2 Write) 
00e" AFD} Record byte count 
AFD4 Counter: when 0. read/ write ends 


Aa00 AFDS5-AFD6 Pointer to buffer lower limit 
AFD7-AFD8 Pointer to buffer higher limit 
AFD9 Disk read/ write, motor on/off 
AFOA-AFDF 
AFEO-AFEF Current file name (16 bytes max.) 
AFFO Current relative track number 
AFF1-AFF8 Current file data or pointers for 
load or save 


5K buffer 


AAOG Record area 
ABOO Directory 
AC00 area 


Diskmon ROM 











AFOO Current 





AFFF variables AFFS Directory write switch (#105 write} 
BASIC ROM AFFA Command mode (#22-command mode 
. AFFB Orive number ( 1-8} 
AFFC Sector number {1-t0) 
AFFD Disk command byte 
AFFE Register save area 


AFFF Track number ( 0-39} 


a 


BASIC programming with Compu/think disk drives Before presenting programs which 
demonstrate fle-handling with this system, let's look at some general programming 
features. 

(i) Because of the possible bugs in string-handling, programs should begin with 
the CLR command. This may be combined with a memory-lowering POKE if several 
buffers are used; POKE 52,255: POKE 53,107: CLR for example reserves 5120 bytes 
of RAM from $6C00-S7FFF with a 32K system. 

(ii) The directory of these disks provides no information about @ file type. For 
this reason the manual suggests that sequential files are given aames ending '.SEQ'. 
Program files names ending '.BAS', machine code filea names with '.GO', and so on. 
This js entirety optionr]; programs will run without these codes, but readability is 
helped if some convention is used. 

' (iit) When a file is opened, either for reading or writing, the spindle motor is 

eft turning, so that delays due to motor start are minimised. (The LED on the drive 
will atay on). To save wear, the motor can be turned off (sce the jump table for the 
§YS command), and turned on only when needed. A delay of at least a half-second Is 
tdyised in the disk manuuls before writing or reading Igy attempted, Bo that the motor 
Speed has time to stabilise at its correct value, 

(iv) Diskettes need formatting oOcfore use; this is a write-only operation (which 
works even with head-cleaning diskettes}. All diskettes should be formatted. (Some 
pith have a strangely: worded warning which seems to imply the exact opposite). 

inks do not need to be ‘initialised’ in the CBM sense. They have no names or other 
kientification; In practice the label is a sufficiently good reminder. 
7 (v) $C (close fe) writes a null character, CHRS(0), onto the end of the file, 
alah thls can De uscd as @ marker in the same way that ST=64 may be used with CBM 
rt 5, In either 2age, the alternatives are to record the number of records, perhopa 
another fila, oz ta write one's own end of file marker, Because of the arrangement 
¥ tracks, unclosed fifea are jens of a potential hazard than with CBM drives, 

(vi} Records are terminated by CIIR$(13), the carriage return character, 

(vl) In program mode, a ‘fila not found’ flag exists, so that thls type of con- 
struction ia powsibla: 

1900 POKE 44978,0: $0,0,"R",°82ZQ FILE" 

1QL0 IF PEEK(44976)=255 GOTO 10000. AXM ERROR-HANDLING ROUTINE 


ai (vil A number of routines, built Into CBM disk DOS, are only avalinble In thls 
abhi aa ASIC proKrama” on disk. This inchices fille copy and disk copy utilithes and 
ha hielo to rend disks recorded with different denaitios. Some verfuions of the Clie~ 
a Ing program don't work, MONITOR ja a tung BASIC program which perfurma sim - 
ae unctlony ta SUPERMON and EXTRAMON, but more slowly. Tha tiny assembler has 
* dircetlyas (ORG, EX1, BYT, ADH, TXT, END) of which seme are implemented, Tha 
Serton won't scroll: 163) MEeO/ S36 MKeKKeLs 1600 COTO 1938/ delete 6662 remadioen this, 


me MPF ve, « 





Programming the PET/C8M ~ 204- 6: Disk drives 


RANDOM-FORMAT computes the parameters (i.e. low and high bytes of number of 
records and record length respectively) of a specified 'random-access' file, for those 
who haven't found out their secret. DISKCOPY provides duplicate or backup disks: 
the copy process proceeds one track at a time, and these are recorded on the sereen, 
A track which is difficult to read or write causes 9 noticeable delay; this can be help- 
ful in identifying weak disks. Severat test programs are available. They are not ex- 
haustive, and lenve much of the diskette suface untested. There are also RAM testing 
BASIC programs. A few technical test programs (BOARDTEST, HAT,NK1L) exist. 


Demonstration programs showing file-handiing These short programs are similar to 
those in section 6.3 on CBM disk drives. The commands are not very different from 
BASIC 4: 


DEMONSTRATION OF A SEQUENTIAL FILE. WRITING TO DISK. 
10 $0,1,"W", "SEQ FILE", "ABCDEFGH"” 


(COMPU/THINK) 


‘REM THE PARAMETER STRING CAN BE CHOSEN TO 
MEAN SOMETHING, IF YOU WISH 

40 FOR J = 1 TO 10 

30 X$ = "RECORD NUMBER” + STR$(J) 


40 SW, X$ 

43 PRINT X¥ :REM REPEAT ON SCREEN 

$0 NEXT 

60 $C REM CLOSES THE SINGLE QBTAINABLE PILE 


There is no statement corresponding to the CAM's APPEND; without elaborate work in 
the tracks holding the file data, it is therefore impossible to extend such a file once 
written. Also it cannot be read and simultaneously written, with corrections, to another 
file, because of the restriction of one open file only. 


DEMONSTRATION OF A SEQUENTIAL FILE. READING FROM DISK. 
100 $0,1,"R", "SEQ FILE", I$ 


(COMPU/ THINK ) 


:REM I$ SHOULD ALREADY RAVE BEEN DEFINED; ..-. 
210 FOR J = 1 TG LL sREM I$ NOW SHOULD BE “ABCDEFCII" OR OTHER. 
120 $R,X$: X$=XF+"" :REM THE PATCH MAY HOT BE NECESSARY 

125 PRINT X$: IF E$=CHA$(D) THEN PRINT "END OF FILE POUND": GOTO 140 

130 WEXT J 

140 $¢ BEM CLOSE 


Note that old records aren't deleted; if end-of-flie ls ignored or not tested, it may be 
possible to read remaining records left from an earlier, probably longer, Cile. 


DEMONSTRATION OF A ‘RANDOM ACCESS' OR RELATIVE FILE: BOTH READING AND WHITING. 


The firat bricf program allocates tracks and directory entries for a file called ‘R FILE’ 
which has a muximum of 4000 records of length 80. (This includes the final carriage 
return, and the record is stored with total length equal to 41 bytes). 


10 19 = CHR9(1396)+CRRS(19) +CHRS$ (80) +CHAS(O}+"XIXR” REM 199256 + 136 = 5000, & 
p 0*256 + sO = 60, 

20 90,2, "Ww", "R FILE", 1$ :REM OPENS FOR WRITE LIKE A SEQUENTIAL FILE 

30 FOR J = 1 TO 6000 

40 $W,BLS 

50 NEXT 


6a $¢ 


The polnt of writlng spaces [6 to erase previous data from ail the records. Thla can be 
tlne-consumlag. Unllke the CBM equivalent, these files don't automatically enlarge 
themasclyes If raked to rend a reeord beyond the curcent moximum number, flownver, 
Ike CBM relative files, they can be cilher written to or read from when open; they 
are not explicitly opened only fur one er uther of these operutluna, Consequently files 
of this type are usually more often unmed than sequential filles. They can be updated 
whRe Information If entered from the kuyboard, or Crom other non-Compu/think files, 
auch as tape flies, or CHM dlvk unitn. But they cannot be updated evally from a fle 
of Compu/think date without some programming effort, auch aa atoring the mew ite 
in string neraya In RAM, purhapa eerending a file several tines, while the relative 
file ia cloned, (9 read ali the records in it, Thia la one ef the penaltlea of the more 


almple opornting system of Diskaion. Tha next page hos a read and weite damonatration 
program :- 


:REM BL$ MUST B£ A BTRING OF 80 SPACRG HERE 


6: Oisk drives 
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5 RSH"": Sa"? 

19 $0,1,"D","R FILE", I$ 

20 INPUT "READ OR WRITE", RWY 
30 IF RW$="R" THEN GOSUB 100: GOTO 20 

40 IF Rw$="W" THEN GOSUB 200: GOTO 20 

SO $C: END ;REM ONLY R AND W ACCEPTED 


100 REM ** READ RANDOM ACCESS FILE ¢* 
110 INPUT "READ WHICH RECORD"; N 
120 [F N<l O8 N>S000 GOTO 110 
130 $READ;¥,R$: R$=R5+"" 

140 PRINT RE 

150 RETURN 


200 RE ** WRITE RANDOM ACCESS FILE ** 
210 INPUT “WRITE WHICH RECORD"; N 
220 IF N<1 OR N>5000 GOTO 210 

230 INPUT "TYPE IN RECORD"; R$ 
240 IF LEN(B$)>79 GOTO 230 

250 IP LEN(R$}<79 THEN R$=RS+" ": 
260 $W;N,AS 

270 RETURN 


REM "D' MEANS ‘DIRECT ACCESS' 


;REM $R AND S$READ HAVE THE SAME EFFECT 
;REM PRINT RESULT ON THE SCREEN 


GOTO 250 :REM PAD WITH SPACES THE LAZY WAY 
REM WRITE THE RECORD WITH C. RETURN 


Reading and writing tracks The following BAS!C routine {which is easily converted 
into machine-code} reliably loads any track into the normal buffer from $9000-SA3FF: | 


700 REM ** READ TRACK TR OF DAIVE DR INTO $9000-$A3FF (36864-41983) 
710 POEE 45041,DR :REM POKE DRIVE NUMBER INTO AFFS 

720 SYS 45062 yREM MOTOR ON {ALSO READS DIRECTORY). BOOG 

730 POKE 45055,TR :HEM POKE TRACK NUMBER INTO AFFF 

740 SYS 45083 +REM READ TAACK INTO NORMAL BUFFER. BO18 

750 SYS 45095 >REM MOTOR OFF ~ 8027 

760 RETURN 


And the opposite process, of storing a track from $9000-SA3FF onto disk. is carried 
out using the write routine SYS 45080 (B018) in place of line 740's read routine. Sa 
@ general read/ write routine for this buffer might be: 


700 REM ** BUFFER READ/WRITE: TR=THACK, DR=DRIVE, AW$="R" OR “W" 
710 POKER 45051,D#: SYS 45062; POKE 45055, TR 

720 IP AW$="R" THEN SYS 45989 
730 IF RW$="W" TREN SY8 45080 
740 BYS 45005: RETURN 


It ls atso straightforward to load tracks from non-standard parta of RAM, and read 
them back - if required, into different RAM areas. All that's required is to poke the 
low and high addresses, and use a similar routine to those above, except that the 
routine which reads or writes is sclected to bypass the allocation aubroutine for these 
buffera, (Hor example. the slight difference on disnasembly between $B018 nnd SBOLE 
‘Is taken up by this allocation routine). The low and high pointers are (SFB) and ($C9} 
Teapectively in BASIC21. For example: 


800 REM ** BUFFER READ/WRITE: THIS EXAMPLE USES $6CO0-S7FFY 
810 POKE 45031,0R: SYS 45062: POKE 45055,TR 

$20 POKER 251,06: POKE 252,198: Rim NOW {FC} HOLDS 96000 
830 POKE 201,253: POKEZ 202, 127: REM AND (C9) HGOLDB srry 
B4 [PF RW$e"R! THEN SYS 45089 ‘AEM BO2L 

850 JF RW9="W" THEN SYS 45044 iREM BOLE 

860 BYS 45005: SETUAM 


There Is of course no probicm in parameterining this routine further, ao that entry of 
the lower tlmit of a buffer entculates the upper Hmit and pokes all four bytes. Note 
that a baffer need not hold $120 bytem; the directory for example in loaded inte & 
shorter buffer, typleslly 1900 bytes long, If ihexe routines ara now ta you, try exper- 
imonting by adding Input atatementa for drive and (rack numbers, enlllng a read sub- 


‘REM IDEALLY, SIGNAL ERROR IF AWS=OTHER 


(BASIC 1:247 & 248) 
{BASIC 1:229 & 230] 
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routine, and displaying the result with, for example, 
PRINT CHR$(24);:POR J = 36864 TO 41983: PRINT CHR$<{PREK(J));:> MEAT. 


As many as 7 buffers can be simultaneously stored in a 32K machine, at the expense 
of space for BASIC (7 buffers leave 1K, 6 buffers leave $K, for example}. There la 
considerable scope for machine-code searching of RAM and similar activities. Self- 
checking haghtotals can be introduced quite easily. Tracks may have their track qum- 
ber, drive number, and a hashtotal stored in three bytes at the end of the track; in 
this way, an entire disk can be tested for its data’s self-consistency with a simple 
program to consecutively read and check each track, These possibilities suggest that 
several CBMs tay be joinee to one disk unit, since reading and writing can be made 
infrequent. but I suspect that the necessary boards with RAM and EPROM may not be 
available independently of the drives. 


The directory track Track zero, the outermost track, holds the disk's directory, 
unless the disk Is used in some special way, when it may contain data. Each file has 
directory entries 25 bytes long, The entries are quite simple, and the fotlowing dia~ 
gram illustrates a typical disk directory. Note that the file names have been printed 
in ASCUL characters for readability, with & representing a single space character, and 
the remaining values are represented by the PEEK value, again for readability. 





ae -—— —] 
Relative Starting Address or End Address or Rest of [$ or i 


Track No. | Number of Rel. Records} Record Length Seg. file parameter 
5 4 as 27 32 32 32 32 















a= FILE NAME -- 
BACKGAMMOND SYED 








BACKG AMMONS Wes a 1 at 32 32 323 32 
MERGE . COPSENU EYE 1 ft) 61 3232 #32 «432 
UTILITY .DATHb WHE 1 3251325288 49 323 
(i.e, 3 481 J 
GALLFILE OIRWESW 1 236 t) 32 32 32 32 
ennenneeee----- | OTHERS | -eseeennoener- 
GALLFILE. DIRBBWW| 17 236 r) 32 32 33 32 
FREEVTRACKD PHB S| 255 32 32 32 32 32 «32 | 











Each entry has (i} 16 characters of file name, padded with apace characters. 

(ii) A relative track number. 'FREE TRACK' has a symbolic value of 255. All file 
treks are numbcred consecutlvely, starting from 1. Note that a file is 
assigned the earliest empty tracks, 80 4 file may be interwoven with other 
files once some erasure of files has occurred. 

(lil) 8 bytes of parameter. ‘Chere is no indication of the type of a file; a program 
be read as a random aceess file, or a sequential file loaded as machine-code. 
The result of such experimentation depends on the 8 parameter bytes, which 
are interpreted in three different ways, viz. starting and end address for 
machine-code and BASIC flies (BACKGAMMON and MERGE.GO in the example) 
or number of records and record length for random-access files (GALLFILE. 
DIR) or « string of 9 user-assigned charactera (UTILITY.DAT haa the dale 
of fast update = 3 4 a1 for Instance). 


The program HACKGAMMON starts at 4"256 + L = 1025, and ends at 27*256 + 88+7000. 
This ls a BASIC program ag its starting polnt implies, although it could be machine- 
cude. It is about 6000 bytes long, and therefore Gecupies two (racks. MERGE.GO 
atorts at $2000 and extend to $4090, sinnll emnigh for 1 track. UTILITY DAT iso 
short sequential file. GALLFILE OTR ia a very long direst accusa file; Ra parameters 
show it to have space for 46*256 + 236 + $2012 records of length @ each. In faet, the 
system allocates space for T bytes In cach of these recorda; thia is a peculiarity of Ine 
system, 17 tracks are newidard for the resulting file, Flanity, we see a PREE TRACK 
ontry; all unused tracks contain this, Very secasionnlly, the word ‘bad’ appears in 
reverse after a file name entry. The directory ia printed by a special coutine (fallow 
$D to find tt - e.g. BAI in BASIC 2), Thin Nata only fllenames with relative Crack 
number 1, to aveld repetition. The number of free tracks Is enloulaled simultaneaualy - 
it ia interesting to note that because of ihla, fltes can be reeprded inn way a@bich 


‘5 AMMO. rE er A AP NG PE UE Pl ta II ORO PETS IT ST EL ET eI 


“Se omen cae ammennameieym meee eee 
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makes them invisible on the directory: if a file name ia longer than 16 characters, the 
length is not checked, but the name overwrites the relative track number. So tong as 
CHRS$(1) isn’t written in the 17th position, the fle won't appear. This character 
should not be CHR$(255) or the file will be overwritten. Note that only 16 characters 
are compared during a load ar save operation, so the first 16 characters must differ 
in some way between different files. (There is no system of default fe names, like 
Rett or "BAS*" with CBM drives). So a program saved as “LENGTH=SEVENTEEN!" 

is invisible on the directory, but will load by $L,1,"LENGTH-=SEVENTEEN". 


The short program which follows analyses the directory track, printing the con- 
tents of each track, or of one single file name when this is found. For example, a 
disk has a program called ‘PRINT PRICE LIST‘; the program comes up with this: 


NAME: PRINT PRICE LIST 


ABS. REL, -LOW PROGRAM BIGH- SEQ.FILE 
TRY TR# #RECS R.A.FILE LEN~ 1$ PARAM 


we 1 1025 BASIC 11604 . 
17 4 1025 BASIC 11804 
18 =63 1023 BASIC 11804 . 


Showing the three tracks which hold the file, which ia presumed by its start address 
to be BASIC, and which extends from 1025 - 11804. I$ is not important. 


10 REM **DIRECTORY THACK ANALYSER FOR COMPU/THINK 

20 INPUT "WHICH DRIVE"; DR; IF DA<1 OR DR>4 GOTO 20 

30 INPUT “FILS KAME"; FS 

40 IF LEN(F$)>16 GOTO 30 

$0 IF LEN(FS)<16 THEN FS$=?$+" “: GOTO 50 

100 PORE 45051,DR: SYS 45962: POKE 45055,¢0 7REM TRACK OG 

210 8Y9 43083: BYS 45093 i:REM AZAD IT, CLOSE DRIVE 


200 PRINT "NAME"; F3; PRINT 

210 PRINT"ABS. REL. -LOW PROGRAM HIGH- SEQ. FILE"; 

220 PRINT"TR# TR# #BECS R.A, FILE LEN- I$ PARAM" 

230 DIM DE$(39) :REM FOR 40 TRACE UNIT 


300 IN = ASC(FS) TREM INITIAL VALUE FOR FAST TEST 
310 FOR DE = 1 TO 39: IF IN«>PEER( 36639 + 25*DE) THEN NEXT: GOTO 500 

320 FoR DE = DE TQ 39 ;REM BUILD TABLE OF NAKES.-. 

330 K = 36039 + 25*DE 

340) «IF INC>PEEK(E) GOTO 390 

350 POR J = K TO K+iS 

34000)«—-:DES(DE) = DES(DE} + CHRS(PEER(J)) 


AEM... IGNORING [MPOSSIBLE ONES 


370 «=NEXT J 

380 JF F$<DE3(DE) THEN Nek: GOSUB 450 

300 NEXT DE 

400 IF MeO GOTO 500 :REM PILE NOT FOUND 
410 EXD 

480 PRINT DE TAB(4) PEEK(J) TABCi0) PEEK(J+1) + 256*PEZR(J+2); 
460 IF 1025 = PEEK({J+1) + 256*PEEK(J+2) THEN PRINT “ BASIC"; 


470 PRINT TAB(25) PEEK(J+3} + 250*PRER(JS+4) TABC31); 

4A0 FOR EK = L TO 8: PRINT CHAS(PRER(J+K));: NEXT XK 

430 RETURN 

50°) REM ¢* FILE NOT FOUND - LIST ENTIRE DIRECTORY 

610 PRINT ¥$; “NOT FOUND": PRINT 

320 FOR DE © 1 TO U8; K = 38039 + 23°DR: POR J = K TO Koi 
339 DESDE) = DRS(DE) + CHASC(PEEN(J}): NEXT J 

$40 PRINT " " DE; DES{DE}; 

550 SEXT DE 
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A similar program can 'Unlist’ programs, by poking an asterisk in the correct place. 
Or it may be modified to Re-list a protected program. Renaming of files is algo easy, 
and some protection can be achieved by including cursor-contro] characters in a file 
name. An ‘Unlist’ program, too long to be included here, has to (i) search the direct- 
ory for the specified name, typically by loading track zero into RAM and searching it; 
{ii} If the name is found, calculating the absolute track of the first relative track of 
the file, which is the first met with in the directory, (ili) loading this track, poking 
in 42, and finally saving back on disk. The pregram should vegin with REM, preceded 
by not more than 4 tokens, or some other arrangement immune from the influence of a 


foreign CHR$(42). The business part of such @ program is something like this: 
1010 TR=DE :REM TRACE NUMBER = DIRECTORY ENTAY 
GOSUB 700: REM READ FIRST TRACK OF PROCRAM 
REM EQUIVALENT TO LOCATION 1034 OF BASIC 
a 


1020 RW$="R": 
1030 POXE 36873, 42: 

1640 RW$="¥"; GOSUB 700: REK WHITE MODIFIED TRACK 
1050 PRINT “UNLIST "; F%; “COMPLETE”; £ND 


Machine-code and RAM buffers This subsection deals with machine-code processing 
of data held in RAM buffers. Because of Compu/think's track-handling system, this is 
principatly relevant with Compu/think, but is also usable with CBM disks, in which 
buffers of data cun be loaded and saved by the save command -S8 and its BASIC 
equivalents and .L and LOAD. 

It may be useful to erase a buffer; this short machine-code routine, which uses 
no tero-page locations and is consequently not immediately relocatable, puts zero bytes 
into all locations $9000-SA3FF. it can be modified to erase any set of locations whose 
lower and upper limits are of the form $xx00-SxxFF. SYS 800 runs it: 


0320 A9 00 AA 9D 0O 30 ES DO 
0328 FA EE 25 03 AS Aa CD 25 
0330 03 DO ED A9 90 8D 25 03 
.t 03398 69 
The next example is a routine which searches a buffer for a record. A form of 
indexing may be implemented in this way: & short code or identifier, followed by # 
record number, enables a two-stage operation to find the record by its code. The 
search routine uses a flowchart like this: 








INITIALISE 






Set record no. =1 
Set iow Limit 
Top limit 1s 7FFF) 








Add rec, len. 
to pointer 









‘Found byte' 
eet to l 









Aemult 


eRcurdns 
TERE? 
Fa aa 


| Increment 
(Record huaber 





‘Found byta* 
wet to 256 












> 


a 
— 





Bae 
ba 
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This is a sequential search: records are scanned from one end to the other. When the 
search ls carried out (the routine takes a fraction of a second) a location, 847, is set 
with a coded value to show whether a match was found between a record and the 
field stored in RAM. A value of 1 shows it was found; 255 shows the search was not 
successful, An alternative entry point enables a search to be repeated, if a record 
exists more than once. The diagram ithustrates the rationale behind this type of search. 
A subfield within a record - perhaps a single character only - cam be sought. Given 
that the records are of uniform length, the important starting position jis the point at 
which the comparison fiefd begins; this need not coincide with the start of the buffer. 
The focations used in this example program are: 
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832-846 Sought field, Maximum leogth in 15 characters. 

847 Found byte. 1=Found; 255=Not found, 

848-849 Current recor¢é number. Starts at 1. 

850-851 Start point of search. Not necessarily equal to the atart of the buffer, 











852 Record length. 

853 Length of sought field {1 ~ 15). 

854-855 Current pointer into huffer. 
_ Record Length —————_>¢ — — (—— — — 

Compared field ret —————— 

[x ECORD NUMBERIL | RECORD NUMBER 2Z REFEcCcQORD NUMBERYJ 
Start of . ba pyr 
Buffer 


“ACHINE-COGE SEARCH ROUTINE TG HUNT STRING IN BUFFER 


1 FOR £2854 TO 967: REAG M; POKE tieMs NEXT: REM SE1 "ed 
2 DATA 16'7+ 9+ 16841491, 84) 3+ 169+ 1+142.80+392173>82+5> leiveiyartra/aacaisiaeea 
“ VATA 1/3+86.37441-124,3-+173,87.,30i41-125:3 . 
* DATA JA5>Os Lh 217+ S40 3+ 208) Fs 2007 204 85+ 3s 240) $2> 761123903 
: Pa 24 1739845 de LODe OSs B+ i41, 862 Ar 169105 109; 87-35 141+8709 
: tate 474+ 85+ Se 202s 1FO+ 241 LOFs BGse 3+ 169) 2550109, O87) 3+ 201412761618 
3 A 236+ B0r 3+ 208s 3+ 72590+81+3+ 16010 7H6111+3 
DATA LODs Le Phe L9Ge Br 1S9 VSS eld de 2 Fr oe FG 


FR ANT “CLLR MACHINE COUE BUFFER SEARCH ROUTINE“ 
4 PRINT “{LOWNILOCATSONS: “: PRINT “~-------- 2 
2 ba Lad “ ROUTINE I5 ENTERED AT $3958 (*856)" 

PINT “ OR AT $33C (2908) TO REPEAT" 


2% PRINT “i DOWN] $340 ¢ 
~-$342 (= 892 - 846) HOLO THE SOUGHT STRING" 
- ae “CONWN] BYTE $34F (847) IS [HE CHECK BYTE" = 
is Brent AND HOLDS 255 IF NOT FOUNDs“s PRINT“ 1 IF RECORD FOUND; ~ 
% CENT “CDOWNIJASSUMFE TION [S THAT THE $129 BYTES" 
37 ERINT “FROM $OCUO (27648) TO S7FFF (32767)"5 
eee’ INT " HOLGRECUROS AF "QUAL LENGTH” 
pis REM #® ROUTINE HERE (£G COMfU/THINK TO LOAD TRACK OF DRIVE) ## 
oe FRINT "CLOOWN]OG YOU WISH TO EXAMINE THE 6UFFER? "> 
dong INPUT “IF SOPRESS & KEY DURING FRINTOUT TO STOP”? YN® 
2030 ap YNOR°N” THEN 33000 
RL 27648TU327671 GETXSs IFXS=" “THENPRINTCHRE (PEEK CL) ) 1) 0NE 
x 
ea0 PRINT: PRINT: INPUT “SOUGHT ITEMI": CTS eats 
dogo FOR Los 2 TO LEN(CTS)+ POKE AS1L+L,ASC(MIDS(CTS) LiL) ds NEXT 
Yay UKE 853) LEN: CTS) 
seu. PAINT “ENTER TOTAL KECURD LENGTH (EG. INCLUDING REYURN) “ 
4G PORE mise LENGTH*2 FOR COMPLETE SEARCH) "1 R 
1 KE SDs 
0 inet “START OF SEARCH (EG 27648}1°s3 
59 ra ea ad POKE 830-6-1NT(5/256)#256 
‘+ a 
Pine : ee SELINA TE CONTAINS "+ PEEK(&47) 
Pat “CUOWNIKECUHD NO (START#L) 191"7 PEEK ’ * 
doag gh PEEK(A47 "255 GOTO 4060 eee ee ge 
49% ADAG : Bue ger yet THEN INPUT "REPEAT THIG BEARCH?”? 
ey" HE 
Se ens EN SYS 708) GOTO 4010 


YNS 


dens 
Pn . 
TS eA (rCm Plena era A AEN ST OTE SSE RETE GT Fear 
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6; Disk drives 
A hashtotal routine (Chapter 10} and merge routine (Chapter 3} are also well adapted 
for use with these disks. Techniques involving indexed files, and other uses for 
merges, are not however for the faint-hearted. 
There is no routine to turn off these disks once SYS 45056 has been issued. 
i 


Any other routines using wedges. however, are unlikely to co-exist, unicss the wedge 
is specially written to allow for the existence of other wedges, See Chapter 14 on this. 
However, a machine code routine to do this is easy to write. Because of the time spent 
processing the wedge, there may be noticeable time-saving. perhaps 20-30%. The same 
effect can be achieved by turning off the interrupt allogether, with 

POKE 59411, PEEX(59411)-1 Dut the clock and keyboard are not updated /seanned 
If this Is done, until PORE 59411, PEEK(S9411)+1 restores the interrupt. This may be 
Inconvenient, or it may not, depending on the type of program. A report program with 
no other function than to print out dala probably doesn't need the keybourd on. 


The BASIC>1 code which returns BASIC to normal (so $C for example causes 
ISYNTAX ERROR) is this 14 byte relocatable routine: 


.: O27A 78 A9 BG aS 70 AS 77 85 

6282 71 A9 DO 85 72 60 
SYS 634 (with this location} replaces the first bytes of CHRGET with their normal 
values. This call can be made within a program; its converse, SYS 45956, can also be 
called in program mode, to reconnect the $ commands. 


6.8 Problems, retiabitity, and maintenance 

Problems and retiability Whilst the electronic circuitry of correctly-assembled comput- 
ers is very reliable, it cannot be expected that disk and tape units, and other devices 
with moving parts. should be as error-free, This is not a problem exclusive to small 
the recording head scratches the disk surface) are 
not unknown in latge installations. For this reason, backup copies of data are almost 
invariably kept. There is also, of course, a possibility that human errors will occur. 
Disks may be mislaid, damaged, or demagnetised; or a software error may cause data 
to be deleted or overwritten; perhaps failure to follow some procedure will mean that 4 
disk of usefui data is lost. The purpose of this subsection is to give some perspective 
on these potential difficulties. 


computers. 'Head crashes’ (where 


Minimising the chance of error The following general points apply to all microcomputer 
systems using diskettes. Hard disks (‘Winchestersa') are more reliable; nevertheless, in 
any applications where toss of data or programe would be inconvenient, similar pre- 
cautions ought to be taken. 

(i) Use some systematic copying method. A commonsy~recommended technique te 
the ‘'grandfather-father-son' method, in which each disk has an earlier version pre- 
served and a stil eurlier one, in this way, software errors or errors in the way data 
haa been processed can be corrected by repeating a procegs on the original version. 
The point at which a copy is taken hag to be decided on empirical and common-sense 
lines. Systematic labelling of diskettes helps. The ‘header’ feature with CBM diska, 
and the disk i.d., can be useful here. A log may be kept of dates on which copies 
were taken, and the processing which was performed on them. Important disks - }.4. 
any disk containing information difficult to replace and worth keeping - also need 
physical storage in a place where they wil not be confused with other disks and are 
not likely to be damaged. They may. for example, be kept In lockable boxea, or in 
clearly-marked cases in a lockable drawer. Similarly It may be worth keeping copies In 
a different place - ancther room or another building - for rccurity. 

Ub Ensure that all diskettes are storing date correctly. Since all the data ls 
stored on diskettes, which are inherently a somewhat deilcnte medium, it makes gool 
ponse to have technlques to validate them, In the case of new dinkettes, If they are 
deatined to atore valuable information, they should be tested therougniy with o uthity 
program which writes and rends back every location on the dlakette's surface, This ts 
worth doling even with dinketten which are warranted arrof-free. Mont leat programa 
aren't exhauntive, and confine themaelves ta opaning a few files. Sectors or tracks ©! 
random data can be used. Alternatively, the bit patterns in HAM tenting are auitadla 
(i.a, 1010 1910 and 9101 GLOL, SAA and #$55 and CHRS(1T0) and CIHRSCRS) are the 
hexadecinal and ASCH equivalents). Dinka which hold data need a different approach. 
The point la that @ user haa # nat of diaka in envelopes which are unreadadlo tn the 
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normal way, unlike card-indexes or ledgers, say. It is important that validation pro- 
grams should exist which enable a disk to de checked for self-consistency of its data 
providing some reassurance that its data does, in fact, correspond to its label. This : 
precaution is quite often lacking in many systems, notably those from the cheap end of 
the market. But it is difficult to see how a user can have totai confidence in a system 
lacking a verification facility. As an example of the type of thing | have in mind, a 
system's disks may be run through a program which calculates a hashtotal of a batch 
of data, and compares it with the same hashtota! previously stored on disk, reporting 
the results. Or a utility program may page rapidly through all the records, cr 4 group 
of them, displaying the results. Or a routine may check the integrity of files by read- 
ing consecutive sectors through to the end. In this way, a diskette which perhaps was 
exposed to a magnetic field, or is otherwise suspect, can be checked without an actual 
program run. If this aspect of a system is thought out at the time of design, the 
subsequent effort is likely to de less than if it is introduced as an afterthought. 

ii) Don't overuse disk drives. Error rates are usually quoted as a proportion 
of disk accesses attempted. While this is a statistical artefact to some extent, it is true 
that drives which continually write data all over the disk‘'s surface are more likely to put 
& sector in the wrong place than the same drives under conditions of less heavy loud- 
ing. Other things being equal, it is likely to be good policy ta cut down on disk use, 
For example, when relative files are opened, CBM's DOS allocates only enough disk 
space for the current records. If a relative file is intended to grow, it is best ta gen- 
erate the entire length of the file at the start, so that sectors will tend to be arranged 
in a tidy pattern, not interspersed with other data. A new diskette, free from the 
chaotic organisation of sectors resulting from many files being saved and fater scratch- 
ed, is a better vehicle for rejative fites for the same reason, that track-sceking move- 
ments are reduced. Data which is frequently reused may be better stored in RAM than 
repeatediy read from disk. This rule, hawever, is very dependent on other feutures 
of a system. if, for example, the chance of the computer being switched off or losing 
data in some other way is greater than the (small) chance of disk failure, then data 
should be stored immediately on disk. 

(iv} If possible have a standby system. An advantage of microcomputers is that 
exact duplicate systema may be easily acceasibte, in the same organisation or user 
group. When they are, reciprocal agreements may be possible, so that even serious 
breakdown doesn't affect a system's work. Organisational quirks may make this more 
difficult to arrange than appears likely at first sight. 


Summary of software bugs These remarks apply to CBM disk units with DOS 1.x or 
BOS 2.x, including 2.5; mew releases of DOS will make the comments obsclcte, for 
balk hehe ould Pd ate ae time of writing, definite announcements on DOS bugs 

requent from Commodere. and in i 
lol il ba the adsence of fact, it it not surprising that 

di) Write- protect taba. CBM DOS detects the existence of a write-protect tab, 
which prevents an immedinte write to the disk, as it is intended to, But a software bug 
in the internal processor leaves the head's write-gate enabled, ao that as ea diskette la 
Searched by the head, a magnetic trace moves across the disk, erasing data, syne 
marks, and so on, The effect Is ax though a small magnet hud run over the diskette; 
much of the data will be destroyed. Dori't, therefore, use these tabs with CHM cisks. 
thet (il) Duplicate disks. There is a potential problem with dupllente disks; since 
ed oo is the same, they're treated as identical by the machine, so that the wrong 
en @ palr, one of which has been updated, used by accident, while DOS stores 
the other's HAM, will cause a wrong BAM to be written, and cause acctora to be put In 
fe rie places. Thins ia not likely ta be a sorlous problem if all disks cxeupt back- 
eine ea l.d.8, or if diska are not taken out and replaced by others with 
inition i pais alao not 4 problem with the newer drivas which automatically 

{iii} Uncloned flea. COLLACT or PRINT#1§,"¥..." is the command which erases 
aoe files. Again, this ia not likely to be a problem, since it fa rather oasy ins 
aoe files, Program development Ia a likely time for thin bug to atelke, since a syntax 
Thor shorts fies, which may not ba closed properly aflorwarda, 
ae {lv) COPY. This la a uneful command, which unfortunately has a buy when uaed 
dite py an ontire disk, e.g. In COPY DO to D1 or PRINTEIS, "Ci-0". If the diska have 

erent {.d.n, only @ Files can be copled al one time, Also, relative filen often copy 
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rongly; a utility such as COPY/ALL is preferable, or BACKUP of course can simpiy 
reste a duplicate disk without bothering with COPY. Note the syntax of COPY and of 
ae equivalent PRINT#15 command. The reversal in order of the drive numbers can 
ause a file to be wrongly replaced dy its earlier version. BACKUP and PRINTALS, "D.? 
ave the anme raversal. This will not be a problem unless a user is careless; the best 
‘recoution is to use 4 program with explicit instructions to help perform these func- 
jons. 

(v) Relative and sequential files. Several files can be opened to a single relative 
ile. This is probably best avoided; there are several reports of buffers being wrongly 
fritten in these circumstances. Short relative files, with total record length Icss than 
54, may have incorrect side sectors nllocated. Make thein several sectors long at least. 
308 2.8 can fill only about a third of the disk with a single reiative file; several may 
1ave to be used where one would theoretically be best, However, it may be unsafe to 
yrite to relative files when several relative files are open; ‘Before the write is complete 
| buffer may get overwritten’, is one theory. The best way of using relative files 
wens to be not to have several parallel files, holding between them data on items 1 to 
4, but to have several files covering the range 1 to N/3, N/3+l to 2N/3, and so on; 
n this way, the minimum number of files need be open. There sreother rumours; ta 
quote Jim Butterfield, ‘There are a lot of rumors flying about ... you hear a tot of 
stories you can't believe’. One of these js that sequential and relative files ought not 
‘o be mixed. This may be a legacy from DOS 1, when relative files were a different 
species altogether, and secms to be without foundation. 

{vi} A disk full error causes files to be left unclosed, since there is insufficient 
apace on disk te store the final sector. Use COLLECT if this happens. (It should in 
any case never happen with a properly organised working system). 


Software problems (i) Timing. Whenever lurge amounts of date are going to be stored 
on file, or when complex processing ig to be carried out, the usual guesstimate style 
of inferring processing time from benchmarks based on small files should be replaced 
by an accurute trial. If this isn't done, it may be discovered late in the day that a 
sort takes 26 hours, or a sequential read takes 24 hours to get through a file. Test 
data can be generated by 6 program, and used to check the efficiency of a system in 
action. The data may be nonsensical, but its function is to be processed, not to sim- 
late actuol data. Sometimes program redesign can make a huge difference to overall 
processing time. I've seen set of programs whose author didn't know about arrays; 
each of a hundred or ag categories was extracted (rom a single file, in ubaut six min- 
utes per category. As 4 result, a report which could have been produced in about 10 
minutes took about 10 hours. 
(ii) Inaccurate storage. Lespite the system of internal checks used by diskettes. 
there is a small chance that data may be stored wrongly; the most likely defect is 4 
drapped bit, where a byte which should be #D0 londs as #90, for example, the correct 
bit pattern of 1101 0000 loading as LOOL 9000. ‘This is only likely to happen to old 
disks which have been untouched for some time, and is a very uncommon fault. But it 
is not impossible; I've found examples in old copies of DOS Support programs. The 
ensieat way to check for this, if It ia Felt to be nevesnary, is to use A hashlotal pro- 
gram to conflate all the bytes of the program into a single-figure value, and check 
that the value agrecs with the figure computed. This ja a simple thing to do: sec 
Chapter {4 for an example. Again, it is rarely dona, In spite of the extra assurance 
It provides that a progeam haa correctly loaded, This seems u pity, since long machiné 
code progrums are difficult to validate In any olher way, and 4 few incorrect bytes can 


cauao buffling failures und errors. 


Diskette care Most diskette cavelopes have a set of symboth printed on the back. 
providing pletorial warnings eyainst ainitreaiment, Smoking and gust cut Ganage Ube 
surface, atid: slowly dayradye the performance, Magnetism i4 an vbyiour tasard: electric 
motors, TY sets, VOUS, transformers, telephones, demugnetizerds cur all heip to erase 
data from disks, Diskelte boxes cum be Tined with metal folt ta pravire Varnday allied 
Agalast magnetine; this locks eilielent and may actually be useful, Same people belluv? 
(hat underground trains oil A ray scatners car cream disk unless they are metat- 
wrapped. Disketles enn be damaged Cylitehud') by sia pulses of magnetinin if driver 
kre Lurned on or off with disks in piace. The probability of hum ta reduced if the 


drive doors are uped, 4640 ane NOSO alpives, usgiike thal geredecosmacd, Maier mates ie 
thia respect. Sole that the cartier drives dent have a ceniaring meenantom for. iat 
haar 


diska, so the recommended procedure ia to keep thea drive door open unt the dlaik 
begun to turn, 


ec 
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7 ; , 
fe sublested ite. la Pulm del tbat ae digesta disk drives should ideally not 
é sua ‘00 i i 
much. individual manufacturer's units yare in, thely ronlieneey Oe anit eee 
palueimens quite easily, so that disks become more likely to be non-interchangeable 
pee drives; others are more secure and robust. A sudden movement in one direc- 
ion iad be more harmful than in another direction, Facts on this topic are hard to 
brea arth en towards the anecdotal ("X used his system for a year without any 
hoxdea Se ae sold in the U.K. to date have deen Americun, The tong trans- 
alan yearly ae rae journeys aren't always good for these machines. Often they 
Bali pat arth without being unpacked and checked, a fact which annoys some buyers. 
ete eee anse Pe usuelly concerned with the heads: these can be cleaned with 
tera a a gotvent such as isopropyl alcohol, or with @ head-cleaning diskette 
a a diskette case housing a diskette-shaped thin absorbent cloth. 7 
Gaps ee are serviced by cleaning end lubricating the appropriate parts, per- 
ne hase tila 1a cone bY checking the track ser ee announced, and realigning 
F 8 @ track zero end stop, and usin i 
Reka pies Master diskette to check the output from the head’ Disks of mie. eae 
peak Sea geinels (in the technical sense!) so a suitable high-frequency oscillo- 
the coe. 3s 7 ana (called a ‘Cat's eye') of two adjacent areas on the screen of 
i Molde eat when these areas are equal the head is in the middle of its track. 
thee fear Is checked too. The price-range of disk units is such that servicing 
Gd cca wiih 3 poagay and there is considerable temptation for dealers not to get 
be gee sehais ree sort ° work. For example, a sales director of a British chain said 
wor wee ee uh to get involved with hard disk units, because it would take another 
arenas ns Serie engineerg. [t is therefore worth making sure that you have 
chafacs hss Li ers y competent dealer, or to peopie whose business it is to design 
teeeeruiie es Sublet ce The werk is sometimes farmed out to other organisations; 
iad ag All tb aa oeataae and from a consumer viewpoint it’s easier to 
ea tiga ane oe gipnude. a maintenance organisation which is completely differ- 
* re because of a software quirk 4 unit may appear to be defective when 
pe Pieiaa pAb sedans fault. One example with Commodore's series of drives is 
rt i e use of two processors in those drives: the interna! one can be lost, 
eeessible to the IEEE. Initialization wili bring it back to life. 


There are several points worth mentioning about the 905@ series CB i i 
rns its descendants. The doubie-sided versign, ceallad the 8250, runs a pos tani 
ed Mqaaetauned different from any 9050 DOS; Commodore may have problems number- 
eft He su ecauent ROM issues for the 8050 because of this. The 8061 and its double- 
raid equivalent the 8062 (8 inch IBM compatibie diskettes}, in spile of appearances in 
peebene cr Tie be pre-empted by the 8250, and perhaps not appear, On shipping 
moan oft aH units: '... the #050 drives sre intended to floal Freely within their 
Sutoute nie beret in shipping, the outer case flexes against the too tight 
orliieal as bra ending ane drives. This in turn misaligns the heads, which ore very 
Mcrandiecg ts octal density drive. Moral of story: deslers, leurn how to realign 
New ee tegen + This is Jim Strasma, quoting Bill Seiler of Commodore in Canada. 
Shujart pres andon disk drives, replacing Micropoils, which themselves succeeded 
aoa a ; ary are presumed te be mort: relinble, but solid information about this is 
Hoa ae t may be worthwhile specifically ordering the most up-ta-date units, if 
hetatal” nd out what they are. This is 4 puint on which user groups may be more 
i Shire at nae hove alternative views, when compared with dealers who may have 
toe 4h viet y old stock. Finally, a smaller single disk unit ls to be made available 
ad sine i artes to be called the 4031 the ides {9 te provide chenp disk baekup 
aint y users, ike the alngle Apple drives. At the time of weiling the spevification 
urs vague; these drives may be compatible with PET/CHM, or they miy not. 





Programming the PET/C8M -214- 7: CBM disk commonds 

a eee Eee 

CHAPTER 7; ALPHASETIC REFERENCE TO DISK BASIC COMMANDS 

ec I 
7.1 Notes on BASIC disk commands. BASIC 4 has fifteen keywords which earlier RASICs 
jack and which are all concerned with the disk operating system of Commodore's disk drive 
units. They are not intended for use with other manufacturer's equipment. The keywords 
are CONCAT, DOPEN, DCLOSE, RECORD, HEADER, COLLECT, BACKUP, COPY, APP- 
END, DSAVE, DLOAD, CATALOG, RENAME, SCRATCH, and DIRECTORY in ascending 
order of token, There is also a disk status indicator, resembling ST, which takes two 
forms, DS$ and DS. Earlier BASICs cannot list these tokens withoul a special program: 
in fact other keywords from FOR to REM and including ?SYNTAX ERROR will appear in 
their place. At first sight these commands look like radical additions to BASIC: they 
suggest that now we can read and write to disk in a way that was impossible before. In 
fact, this is not the case. The important thing to grasp about CBM disk units is that most 
of the processing is performed within the disk unit. All that BASIC does is send ‘command 
strings’ and data to the disk units, and receive data back again. The disk units are 
“ntefligent’ and carry out their functions without the CBM's processor. Many other 
microcomputers store their DOS in RAM, or in ROM, like the cassette system of the CBM 
range, where it can be disassembled and examined. CBM’s disk system resembles, and 
can be treated as, a 'black box'. What is all-important is the set of ROMs in the unit. 
The early disk operating systems, DOS 1 ta DOS 1.2, have fewer features than DOS 2 
to DOS 2.7, notably the absence of relative files. This difference is independent of the 
version of BASIC which uses the disks. So a DOS 2.1 disk is controllable even by the 
earliest PET but without the extra commands listed above. For this reason I have included 
equivalent IEEE commands using strings containing controlling characters along with the 
simpler BASIC 4 commands. Most DOS systems try to abbreviate as far as possible; often 
clashes between commands with the same initials have to be avoided, with strange cireun- 
locutions like 'X' for 'Exit'. CBM disks have not been free of this difficulty. The table 
shows which BASIC 4 commands correspond to which command string characters and the 
names previously assigned to them. See also Chapter i5, BASIC 4 ROM from $D839. 
7.2 Notes on BASIC 4 disk command syntax, BASIC 4 haa an elaborate syntax checking 
technique (see Chapter 15, SDC68 in BASIC 4) allowing all the parameters including the 
file number to be arranged in any order. DOPEN "FILE",W,#3 and DOPEN#3, W,“ PILE” 
are effectively identical. This has forced out some constructions which would now be am- 
biguous. R shows that a sequential file is to be read; it cannot be also used to indicate 
a relative file, So only the length of the record (e.g. L100) is a parameter when a new 
relative fite is opened. On the other hand, some extra ambiguities have been Introduced. 
Device number 9 may be specified by ON U9 or ,US, Strings and numerals may be en- 
closed in brackets, but need not be if they begin with " or with #9 respectively. All 
string expressions, and numeric expressions not beginning with a numeral, must de in 
brackets, or 7SYNTAX ERROR appenrs. The following four examples of a DOPEN statec- 
ment are equivalent, provided that drive 0 of device #% holds the destination diskette; 

DOPEN@1, "FILE OF NAMESS",U8,D9,¥ 

DOPEN ("FILE OF NAMES" + N$),W,#1 ON UB - REM ANSUMING N$="5" 

DOPEN # (X%), (FNS + CHRS(N)) -REM IP X £S 1, PN$ IS “PILE 

DOPENSL “FILE OF NAMES” |W OF NAMES", AND NeS3 
in this section I have aasumed for conalstency that the command/error channel with sec 
ondary address 15 has been opened with OPEN 15,8,15. ft have used upper-case to 
distingulsh BASIC from ordinary text, and in the BASIC 4 examples used some lower-case 
commands (the 8032 - not the 4000 series though! - powers on Into this moda). 








BAsicc4 BASIC 4 BASIC< 4 BABIC 4 


fe ee ‘aime ee ee 


«ee APPEND Load DLOAD 
D(UPLICATE) BACKUP OPEN DOPEN 

--- CATALOG --- Ds, DSS 
¥[ALIDATE] COLLECT SAVE DSAVE 


C[ONCATENATE } CONCAT N(EW} HEADER 


c[ory) COPY T{NITIAL ESR] ome 
CLORE OCLOSE ore RECORD 
baled DIRECTORY RI ENAME j RENAME 
B{CRATCH } SCRATCH 
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APPEND 


BASIC 4 disk file command 


PURPOSE: APPEND reopens a closed sequential file, setting pointers to the end of the 
file ard preparing to write to disk. In this way a sequential file can easily be 
extended to store more data. 


NOTE: This BASIC 4 command has no direct connection with the techniques 
discussed alsewhere ta join BASIC programs end-to-end. 


Syntax: DOS 1+: APPEND is not directly available; coneatenation of the old file to the 
new file must be used instead. See CONCAT. 
DOS 2+: The DOS interface is ‘Drive number: file name,A'. 


APPEND Is followed by these parameters in any order: 

(i) # then expression for the logical file number. 

(ii) String or string expression in brackets. This is the name of a sequential file. 
(iii) Optional drive number. ,D followed by an expression for # or 1. 

(iv) Optional device number. ON U or ,U with an expression for 4-31. 

Typically this looka like: 

APPEND# arith, expr. ,"name" [,D arith. exp.} {,U arith. exp.]} 


Spaces - except within APPEND itself or the string, are skipped by BASIC and 
have no substantia! effect.* 


Examples: BASIC 4, The first example creates a sequential file called “file of names” 
holding one hundred names, which are assumed to be present in the array N$¢}. 
Some time later - perhaps almost immediately, perhaps months after the file had” 
been written - more names need to be added to the file. By definition, there is 
no aiternative, with a sequential file, to writing these onto the end, The method 
is to open the file with APPEND, and write to the file, as program fine 110 does 
here.When line 120 closes the file, the new data has been appended like this: 


START OF FILE: { recon 1] RECORD 1s +] RECORD 100| NEW RECORD 1). NEw RECORD vf 


10 dopen#] "file of names” ,# ‘rem apen a sequential file for writing 
20 for j=] to 100: print#1, n${j}: nezt: rem write 100 strings 

30 dclose #1 ‘tem close the file 

100 append #2, "file of names" :Fem a,W, are both impiicit in thts 

110 for j*1 to mn: priot#2,o$(j): next : rem write o wore stringa 

120 dclose #2 :rem close the file 


BASIC<4. The example below is exactly equivatent, but omits BASIC 4's special 
Commands. It may of course be run on a BASIC 4 machine, if it is required to 
engure that a program is compatible with any BASIC, 


10 OPEN 1,8,2,"0:FILE OF NAMES,S,W": REM SEC, ADDRESS 18 UNIMPORTANT 
20 FOR J=t TO 100: PRINT#1,N$(J) CHRE(13);: NEXT 

30 CLOBE 1 

100 OPEN 2,8,2,"O0: FILE OF NAMZS,A" 

110 FOR J=1 TO N: PRINT#2Z,N$(J) CHRS$(13);: NEXT - 

120 CLOSE 4 


Notes: [1] APPEND \mpiles both a sequential fite, and ‘write! mode. The reason is that 
appending is not needed with relative files, since any record can be selected by 
Its number. And since the pointers are set to the end of file, reading from this 
point would not achieve anything, Sequentlal flies, because of thelr irregular reo- 
ord length, muat usually be read from the beginning. 


(2) Some CBM dlak manuals omlt thla command. 
Abbreviated entry: e? 
Token: $04 (212) 
Operetion; Boe Chapter 15 under $D977 in BASIC 4, 
ROM entry: The kernel jump address ls SPFAB; thie jumps to $0977. 
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BACKUP 


BASIC 4 disk system command 


PURPOSE: Creates an exactly identical disk for security purposes and for the creation 
of multiste copies of programs. 


Syntax: DOS 1+ and DOS 2+ have the same DOS interface, which is: ; 
'D destination drive number: source drive number’. However, their processing is 
not identical - see note [1]. 


BACKUP is followed by one or two parameters: 

(i) D then expression for @ or i TO OD then expression for i or ¢. 
{li} Optional device number. ON U or ,U with an expression for 4-31. 
Typically, this appears like: BACKUP DO TO D1. 


Examples: BASIC 4. The example duplicates a diskette in drive @ (the right-hend 
drive) onto @ disk in drive 1. The duplicate is formatted (and could be a new. 
unused disk) and copied block for block, For this reason 4 disk to be duplicated 
must be the same type as the drive which does the duplication, since the number 


of tracks and sectors must match. (Cp. COPY), 


10 2? "Place ORIGINAL disk in Drive @ (right-hand drive)” 
207" COPY disk in Drive i (left-hand drive)" 
3) 7:?"Preas apacebar to duplicate” 

40 get x$: Lf x$<>" " gato 40 

50 backup d¥ to di 

60 goto 10 


BASIC<4. The following example performs the same function, without BASIC 4's 
Special command. Note thet the order of disks in duplication 13 apparently re- 
versed! In fact the DOS interface interprets the number after D as the destin- 
ation drive, and the number after the ';' as the source, so BASIC 4 takes the 
two disk drive parameters and sends them on the [EEE bus in this different 
order. If the drive numbers are entered wrongly and the command goes to com- 
pletion, the data will be completely irretrievable; this is why it ia desirable to 
use a program - like the above - with explicit instructions. 

SO PRINT#i5,"D1=¢": REM READ THIS AS ‘DRIVE I BECOMES DAIYS 0°* 


D in this command string is the inltial of 'Dupticate’. Perhaps this was felt to be 
too tong a command for BASIC; hence ‘Backup’. Note that only the initiai is 
relevant; $0 PRINT#15,"DAIS¥1=0" would do au well. 

Notes: (1) Older versions are slower (about 6 minutes compared to about 1-43 minutes 
depending on the type of unit). There ia alao a difference in the underlying phil- 
osxophy: the earlier duplicate command took no account of errors, whereas the 
later BACKUP command aborts on finding orrors. in fact some CHM disks are 
‘copy protected’ by misrecording a few sectors. BACKUP starts at the outslde of 
the disk and works inward. 

(2] Remember that the disk formats muat match. There are (at the time of writ- 
ing!) three of there: 2040 and 3040, 4040, and 8050, Each type of disk muat be 
treated separately when duplicating diake - aeo COPY. 


Abbreviated entry: bA 


Token; $02 (210) 
Operation: Chapter 15 explaliun BASIC 4's operation; the disk unft does most of the work 


ROM entry: The kernel jump address in $FPA5; thin jumps to SDATE. 


i te 
——- es rr 


*Thraughout thle chapter I have aagumed that the command/ error channel hese baer 
Opened with bagical file number 15, thua: GPEW 15,6,15. 
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CATALOG & DIRECTORY 


BASIC 8 disk system command 


PURPOSE: Displays the contents of a CBM disk on the screen, Data written directly 
to sectors will not show up, since lt bypasses the file creation and directory 
entry routines which are otherwise used. Other types of disk. for example those 
formatted on other machines or not readable because of incompatibility (e.g. 395% 
on 4040 drives), will, not surprisingly, not have their directories read in this way. 


Syntax: DOS & and OOS 2+ each store their directories in similar ways, as a BASIC 
Program, complete with tink addresses and line numbers, and zero termination 
bytes to signal that the end has been reached. The difference is that the ‘line- 
humbers' represent sectors occupied by the program or file data, and need not 
be sequential, DIRECTORY and CATALOG (these have identical effects) are 
BASIC 4 commands which do not rety on a DOS interface, but instead display 
the directory by reading bytes, formatting them like BASIC with a number and 
text, and printing the result directly onto the screen. RAM is unaffected, except 
screen RAM, which becomes the storage device. Once DIRECTORY has scrolled 
off the screen it can be recovered only by another DIRECTORY. The syntax Is 


DIRECTORY [D arith. expr. for 0 or ij [, or ON U arith.expn. for device no. ] 


Examples; BASIC 4. Unlike the DOS universal wedge program, this may be called in 
Program mode; this is useful when producing hardcopy stings of the contents 
of a ict of disks. Both CATALOG and DIRECTORY or their short forms, e.g. 
cA and diR, are accepted. Note that this form lacks some of the features which 
are available by loading the catalog as a program, notably the production of 
subsets of the catalog. Since BASIC 4 is designed for use with larger amounts 
of storage than before, this seems a little strange. 





open 4,4: cm 4,;: cA d? : rem print catalog of diskette in drive g 


10 input "drive number";d: if d<¢>@ and dot goto 10 
20 print "(clr} Preas spacebar to pause" 
30 directory d{d)> 


BASIC<4. The directory igs loaded as a BASIC program; this has the drawback of 
overwriting any BASIC in memory, and the advantage of retaining it in memory, 
The disk operating system ig able to identify several useful variations on the 
simpte directory: 


LOAD "87",8 i HEM LOADS DIRECTORY INTO MEMORY; NOW LIST IT. 

LOAD “$1",6 !REM GAME, EXCEPT THAT DIRECTORY IS FOR DRIVE L. 

LOAD "$g: mye", 8 :REM LISTS ALL PROGRAMS, FILES, BEGINNING ‘MY’. 

LOAD "$89: ?7™/Ce" 8 +REM LISTS ALL PROGRAMS, FILES WITH ‘M/C’ IN 
3RD, 4TH & STH POSITIONS (ON DRIVE #9), 

LOAD "$1: FILB*«P", 6 REM PROGRAMS ONLY, STARTING 'FILE*, ON DRIVE 1 

LOAD "$9: 428" ,8 REM DIRECTORY OF SEQUENTIAL FILES ON DRIVE @. 


DOS SUPPORT (UNIVERSAL WEDGE). This program is usable with both BASIC 4 
and BASIC<T. Tra method of displaying the directory {mn identical with thet of 
BASIC 4, at ieast ln outline: some differences may well show up, since several 
versions of DOS support exist. These differences largely affect the [/O proceas- 
ing but not much else, so that one voralon will print a directory to a printer 
efter CMD. another won't. However, the commands sent to the disk are more 
flexible than BASIC 4 will permit, because any charactors can be tonded Into the 
buffer, The foilowlng constructions are therefore all acceptable: 


e009 or 299 + REM DIRECTORY OF ORTVR @ TO SCREEN. 
@ = 60(or 39 REM DIRECTORIZ§ OF BOTH DRIVES AAK DISPLAYED - 
BE AURE KACH HAS A DISKETTE! 

$1: AgsEu* :REM DIRECTORY OF DAJVE 3, BUT ONLY OF PROGRAMS/ 

or $i: ABSEme FILZS WHOSK NAMES BEGIN ‘ASSEN’. 
@85:%=P or >$9;40P ‘RAM DIRECTOAY OF PROGRAMS ONLY FROM DRIVE @. 

. 
me, 
is 
on rc et ERRONEOUS na = 
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tes: (1) Contents of a directory. The specimen “ 
es dente Tom an 8030 drive unit, shows agape fel lo repre TT 
the appearance of # typical diskette directory 22 ieee ceonanee! aa 
on which programs and files have been stored. = i EEPROGRSZS 2 ibs 
The top line prints the drive number, and, in 3% w PELE COE THERES aa 
reverse, the diskette's name and i.d. charac- 2 y 


ters. The version of DOS is indicated, not as 19 “REEPROGCASISETTE" FRG 


4 
’ ud aa SEQ 
2.4 or whatever, but 2A or 2C or some similar 4 "INFO een 
code, 2C is DOS 2.5, the 8050 version of DOS + “PLS een 
2, which allocates space for 2052 sectors {or 4 "Fi ; hoe 
‘blocks') on the diskette. Each filename, in 4 "ALCOA Sen 
quotes, is displayed with the number of sectors 4 ane ar 
which it occupies; the first three programs, 4 "H . een 
for example, all occupy about 35 sectors, und 4 "E1* Seo 
since CBM sectors are 256 bytes long, these + "NA" eee 
c 4 Ne ) 
programs are about 35/4 or 9K of BASIC. “ “vie SEO 
NOTE: files which were not CLOSEd, or which 4 "GPL" SEQ 
were SCRATCHED when open, show various 3 "HLL" SEQ 
warning signs, inectuding file-type DEL or an 1575 BLOCKS FREE. 


unexpected asterisk. At this point, if the data 
is important, the disk should be overwritten 
by a backup; if one has not been taken. in- 
dividual files may be COPYed to another disk, 
with luck. 


[2] Initialisation, DOS 2.1 and 2.5 automatically ‘initiallse' (q.v.) their diskettes. 
but earlier versions don’t. Thia can be done by: 


OPEN 15,9,15: PRINT#15,"19"° :REM “I1" FOR ORIVE 1 
or, when DOS support is loaded, by: 


@I19 or »>f1L 


new disk is put into a drive it should be initialised, since otherwise 
ihe cperstlne syatem ney: write data according to a wrong block availability ad 
overwriting data. [f a program Includes initialisation, or if it ts automatic, the’ 
it needn't be repeated. So directories always require initialisation , unless the : 
disk has been initialised or thia ig an automatic function. {1 hope this is sdeanta 
It is possible to disable (l.e. switch off) the auto initialisation; this is a possh 
though unlikely source of trouble. 


(3] Other versions. The directory ia an exceptionally accessible Piece of code, 
and Tt ta Wstructive to disassemble DOS support or BASIC 4 if you wish to use 
machine code witn diskea. An example; with DOS Support loaded, use the monitor 
to examine the high end of RAM, «.g. 7F80-7FFF in a 32K machine. About 9 ane 
up from the bottom is an §0, a carriage return character, Replace this by 92, .t eh 
hexadecima! equivaient of (RVSOFF]. Now the directory will peint ucrogs the iia 
inatead of In columnar form. Thia BASIC progrem mimics some of the DOS Suppo 
and produces program and file names in columns; 


N 6+0, "80" +REM DIRECTORY OF DRIVE 0 

55 CeThis X80 GETEL: 1¢ iREM REJECT TRACK & SECTOR BYTES 

30 IF X *# 4 THEN X * 01 PRINT: = REM PRINTS # COLGMNS, FUR 80321 

40 PRINT TAB( 208% }7 :REM ae lag Ba elon ee END 

1XMs GETL1, X01 GETA1)X4e a EM CLiTG 

4 ata aie ; 1HEM REJECT 4 BYTES INC. NO. OF BECTONS 
pada i 30 

60 GHTRLeXer TF X84 THEN X © Xo t1 WTO 

70 [F NX® © CHRS(34) THEN @ * NOT Qt CdTO 69 

BO IF @ THEN PRINT X69 tREM PRENT UINLY yee 

90 COTO 40 +REM evs STUFF WITHIN QUOTES 


Abbreviated entry: cA and dik Token: S07 (215) and SDA (218) 
Operation; See Chapter 15 on BASIC 4 and Chapter 14 on DOS Support. 


ROM entry points: Both koywords have the same juinp addeana, $¥P 4 which jumpa 19 
$1873, 
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COLLECT 


BASIC 4 disk system command 


7; CBM disk commonds 


PURPOSE: COLLECT (or Vatidate) rewrltes a diskette’s 'Block Allocation Map’ to 
exclude sectors in files which have not deen closed correctly. The first byte of 
a file's directory entry indicates to the disk operating system that a file was open 
but was not closed. Files are checked, by reading consecutive sectors, for a 
correct termination byte. If this is not present, the file will be assumed to cont- 
inue in another part of the disk, and sooner or later will become entangled with 
some other file. The object of COLLECT its to delete such files and ensure that 
a diskette contains only sound files.* 


NOTE: This command is suitable for data which is held in the form of linked 
Sectors. This includes BASIC programs, sequential files, and {DOS 2+ only) 
relative files. But dota written by the user directly in sectors is not treated in 
the some way, So that the sectors ere de-aifocated from the block availability 
map. Subsequent write-to-disk operations by the fite-handling system will erase 
these sectors as soon as the remaining disk-space before them is full, For this 
reason, disks with ‘user files‘ are best kept distinct from disks with DOS files. 


Syntax: BOS t and OOS 2+ have the same DOS interface: 'V drive number', which in 
DOS | meant ‘Validate’, and was often confused with VERIFY, which is a program 
verification command, not a file verification function. There are differences in 
processing between DOS ROMs, notably when dealing with relative files, which 
DOS | doesn’t recognise. 7 


COLLECT is fotlowed by D and an expression for € or 1, 
(COLLECT alone defaults to drive @). 


Examples: BASIC 4, The example validates or collects - whichever you prefer - the 
files on drive O: 
collect dg 
BASIC<4, This exampie does the same, without BASIC 4's keyword: 
PRINT#IS5, "Vg" 


Notes: ({} COLLECT exists because of the possibillty of corruption of data by files 
which are incorrectly stored. This type of difficulty is inevitable with any disk 
system which allows sectora to be written anywhere on a disk, The problem may 
be a long time in the making: an error may have been working on your disk for 
months, to quote Jim Butterfield. CBM machines are unusual in not having the 
validation as a normal part of the operating system, Similarly, they don't seem to 
have a method of indicating ‘bad' sectors on disks. COLLECT therefore probably 
always ought to be used when progroms and files are stored on disk; but dota 
written to sectors by B-W and similar commands cannot be COLLECTed, since, 
instead, the bi3ock allocation mop will reassign their sectors as unused, and 
aubsequent flte-writing will sooner or tuter occupy these sectors. 


(2] See SCRATCH: thls command too has special properties when corrupted data 
is involved. See aiso COPY with reference to relative files. 


(37 If COLLECT eignals an error - usually fallure to read the disk - the block 
map on the disk [sn't changed - yet. But the block map in RAM will have been 
modified 10 nome extent, probably, go that it's risky to proceed without initial- 
Jzing the diskette agaln, ruloading the old block map, 

Abbreviated entry: col, 

Token: sii (209) 

Operation: $en Chapter 15 for BASIC dotails. 


ROM entry points: Tho kernel jump addreas in $FFA2; thls Jumpa to $DAGS. 

amis comannd-Like many in BABIC-uperates by awltching polatara and Clega, leaving data 
ald Intact. The dats in dud filem etlll exists efter COLLECT, but the file name ta 
Meovas from the directory, and ita aectora are no longer officially in mxiatonce on 
Tecorded by the block aveblebility mag, end hence are lable to overvriting. 


* 
” 
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CONCAT 


BASIC & disk file conmand 


PURPOSE: CONCAT concatenates sequential files, so that the resulting single file 
contains atl the data from the origina! files in sequence. 


Syntax: DOS t+ and DOS 2+ have the same DOS interface, which lis: 
IC Destination drive number:destination file name = drive: first file , drive: 2nd file’, 
After this command, the destination drive holds a file of the destination name 
apecifled, which consists of ‘first file’ with ‘2nd file’ appended ta it. Note that 
CONCAT does not allow a new name to be specified; instead the name is taken 
by default from the second file name parameter. So 6 construction Like: 
CONCAT old file TO newer file GIVING up-to-date file is not available with 
CONCAT, but js available when using the alternative form with 'C'. 


The ayntax is CONCAT [D with expr. for 0 or 1,] file name string or variable 
in brackets TO (D with expr. for 0 or 1,] file name [ON U device number expr. ] 


In practice, this looks like: CONCAT DO,"NEW STUFF" TO Di, "TOTAL FILE”, 
which appends the data catled "NEW STUFF", from drive 0, onto "TOTAL FILE” 
on drive 1, Files which are not sequential data files give an error in DSS. 


Examples: BASIC 4, The first exeinple concatenates two files from the same drive; the 
second concatenates files from different drives. Note that there ia no provision 
tor concatenation between drive units. 

1000 concat 40, ("new data" + str$(n)>> ta dO,"all data” on us 

1500 concat d0,“dateal" to dl,"data” 
The first example could be part of B loop which appends several files with names 
mew data 1", "new data 2", and so forth, onto the file “all data". Note that. 
because the drives are identical, the first file will disappear from the directory, 
The second example performs a copy before concatenuting, 50 that the original 
files both still exist separately. 


BASIC<4. To make the operation of this command clear, I've included a Hating 
of a demonstration program which concatenates a file on drive 1 called "FIRST 
FILE", and a file on drive 0 called "SECOND FILE". The concatenated file is 
RESULT", and is on drive 1. Lines 10-150 write the two sequential files which 
are to be concatenated. Lines 300-330 perform the concatenation, using syntax 
identical to that of the DOS interface, and which avoids the keyword CONCAT. 
Finatly, tines 400-440 read the file calicd "RESULT" and print its contents, to 
show that the required concatenation hus in fact taken piace correctly. The 
syntax of the crucial command ia 


310 PRINTILS, (CL; AESULT#=1:2TRST FILE, @:SECOND FILE" . SEM FOLLOWING 18 OK: 
410 PRINT#LS, "CONCATL: RESULT #1 :FIRST FILE, @:SECOND FILE" 


Notes: [1] Thls command operates by switching the pointers at the end of the first file 
to point to the start of the second. Then the dircctory entry of the second Is 
erased, so the file simply reads from one file to the next: the posltion of the 
sectors on disk wil reflect this history. Relative files cannot be concatenated, 
with ihe present DOS, partly, presumably, because of the greater difficuity of 
programming this as compared with bequential files. CONCAT is closely related 
to COPY; when different Ucives are involved in CONCAT, the first stage is to 
execute COPY, so that the fite to be appended la present on the anme disk aa 
the major file. 


12) BASIC<4 cun exvevtn what is effectively APPEND using conentenation; sll thst 
is needed is the dalu which would huve been written te the file apened by AvP 
END on its own file, which after CLOSE cun be concatenated onto the main file. 


Abbreviated entry: con 

Token; $CC (204) 

Operstion: Sve Chapter 15 for BASIC dowsits, 

ROM entry point: The kernel jump addrasa t4 SFFOI; thly fuaps to DAC?, 


ERT TET 


wee 
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7: CBal disk commands 


DEMONSTRATION OF THE USE OF ‘C’ TO CONCATENATE 


10 OPEN 3°4-50 "La FIRST FILEsSEGQeW” 
20 FRINTES, “FIRST FILE.. 20 RECCROS” 
30 FOR J= 1 TO 70 

40 PR.NTES: "RECORD NO," 

50 NEXT 

60 CLUSE § 

tOO OFEN £8,5»"O:SECOND FILE; SEQ» Ww" 
110 PRINTERS: "SELUND FILE,. 10 RECORDS” 
120 FoR J= 1: TO 10 

130 PRINTES: “RECORD NO. “J 

140 NEXT 

150 CLIISE 5 

160 END 

300 UF!N15+ 48-15 

310 PRINTEL5: “CL:RESULT#L:FIRST FILE+O:SECOND FILE” 
320 CLISE 15 

330 END “ 

40) OPEN 58s 5) “Li RESULT SEQ R™ 

410 INPUTES: X93 

420 FireINT X%# 

426 IF 5T()0 THEN CLOSE $3: END 

$30 NEXTS 

440 GUTO 410 


*RUM’ SETS UP TWO SEQUENTIAL FILES, ONE ON EACH DISKETTE IN THIS CASE? 
‘RUN 300’ CONCATENATES THE TWO FILES INTO A NEW FILE CALLED ‘RESULTS’? 
AND “RUN 400 AEMONSTRATES THE SUCCESSFUL CONCATENATION. 


Trea 

est FIle... 20 RECORISSRECURD NO. 1 RECORD NO. 2 RECORD NO. 3 RECORD NO. 4 RECOR 
“NO, S RECCRD NG. & RECORD NO. 7 RECORD NO. @ RECORD NO. 9 RECORD NO. 10 RECORD 
ED 11 RELURD NO. 12 RECORD NO, 13 RECORD NC. 14 RECORD NO, 15 RECORD NO. 1& RE 
“30 NO. 17 RECORD NO. 18 RECORD NO. 19 RECORD NO. 20 SECOND FILE.. 10 RECORDSRE 
“FOND, 4 RECORD NO. 2 RE URD NO, 3 RECORD NO. 4 RECORD NO. S RECORD NO. & RECO 
“NO. 7 RECORD NO. 8 RECORD NO. 7 RECORD NO. 10 


Mine 
ne ee REE TLE ete He sealant aise Decade deme tiated Bi caicenttiaeninsetied ink ermiars Dalida eacmnieeeaimeaae 
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COPY 


BASIC 4 disk File command 


7: CBM disk commands 


PURPOSE: COPY permits the selective copying of any files from one diskette to 
another, excep! relative fites (at the time of writing). it also permits an entire 
diskette to be copied onte a second ciskette, without erasing the current con- 
tents of either disk except with DOS 1+, in which case each file must be copied 
Individually. Note the distinction between COPY and BACKUP (or DUPLICATE); 
COPY reads the file and writes It back as though it were being written from a 
program; it is added to the current diskette contents. For this reason COPY can 
convert the format of any readable disk into its write format: 3040 diskettes may 
be copied by a 4040 drive. BACKUP is less ‘intelligent’ and produces an exact 
replica, provided the format is consistent. This of course is essential if tracks 
and sectors have been written by the user in ways which can't be read as ord- 
inary files. 


Syntax: 00S 1+ and OOS 2+ appear to have identical facilities as regards both COPY 
and CONCAT, except that DOS 2+ can copy an entire disk when no file names 
are Specified in the COPY command. The DOS interface used by BASIC 4 is: 
'C Destination drive:destination name = Source drive;source filename'. This is a 
subset of the full interface, which causes concatenation rather than copying. 


The syntax is; COPY {D expr. for for 1,][name] TO (D expr. for $ or 1,} 
[name], where both names may be omitted, or both names present. The destin- 
ation file name is checked, and if found to exist, ?file exists error (63) ia sct 
in DS$. So copies made to the same disk must use a different name. 


Examples: BASIC 4. The first example copies an entire disk onto another. Since the 
destination disk is not cleared in any way, the copy may abort with ?disk full. 
Running HCADER first is therefore common - see note [1]. The second and third 
examples copy a file ta the same disk, and the other disk, respectively. Note 
that the names cannot be the same in the second exampie, 


* 100 copy dg to di 
200 copy 49, "text" to d@,"textl” 
300 copy d@,"text" ti d1,"text" 


BASIC 4. These sre the equivalents without the keyword 'COPY'. Note that the 
first example only works with DOS 2+, which was specially extended to include 


it: 
100 PAINT#15,"COPY1=0": REM NOTE THE REVERSAL OF SOURCE AND DESTINATION!! 
200 PRINT#15, "C1; TEXT=0: TEXT" 
300 PRINT#15, “COPYO: TEXTI1<O: TEXT” 


Notes: [1] When converting from DOS 1+ to DOS 2+, cither through ROM upgrade or 
change of hardware, COPY may be used to reformat the disks by reading the old 
flies and writing them to new disks, However, 9050 disks have more tracks, and 
can't be read by smaller disk units, and vice vergza, To copy this type of data 
aceds two disk drives connected to the same machine and 4 copy program: two 
ore avallable through user groups and clubs: COPY ALL by Jim Butterfield and 
another version, COPY/ALL which copies relative files too. COPY with relative 
files gets most of the copy correct, but not all, There in no syntax error. 


(2] Watch for the reversal of urder'betweon COPY and PRINT#15,"C ...". This 
occurs in BACKUP and PRINT#15,"D ..," too. It Im loag serious here; a mlatake 
aimply won't find the source flic, unless lt orroneousty axista on the deatinetion 
file, an 27FILE NOT FOUND ERROR is about the worst that can happen. Ofcaucne 
the destination disk may be copied In ita entiraty onte thr source disk tea. 


Abbreviated entry: coP Token; $D3 (211) 
Operation: Seo Chaptor 15 for BASIC detnils. 
ROM entry point: The kernel jump oddrens is $PPA8; thle jumps to SDAAT,. 
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DCLOSE 


BASIC & disk file command 


PURPOSE: OCLOSE performs exactly the sama function as CLOSE. It has an optional 
form, however, which closes ail open files. The file closed need not be a disk 
file; any [EEE file, opened to device number 4% to 31, may be closed by DCLOSE. 


Syntax; DOS 1+ and DOS 2+ can both handle this command, which is identical, except 
for syntax, to CLOSE. 


The syntax is DCLOSE [rith. exp.} [ . or ON U urith.exp.] 

where the first parameter is a logical file number (1-255) and the second the 
device number. 

DCLOSE closes all files; 

DCLOSE #1 closes logical file #1; 

DCLOSE #1 ON U 9 closes logical file #1 on unit 9; 

DCLOSE U& clases all files on unit #8. 


Examples: BASIC 4, The first example shows individual fites bcing opened and closed; 
the second shows the use of DCLOSE to close all files. The BASIC<4 equivalent 
is in the REM statement. There is little difference between them. 


10 OPEN 4,4 :REM OPEN FILE 4 TO A PRINTER 
20 DOPEN #8,"TEST",W: REM BASIC 4 IS OPEN#8,8,2,"0:TEST,S,¥" (ASSUMING 
DEVICE 8 AND DRIVE @). 


30 --- PROCESSING --- 
1000 DCLOSE #4 ON U4: REM OR USE BASIC 4'S CLOSE 4 
1010 DCLOSE #3 + AEM SAME AS CLOSE @ 


or 1000 DCLOSEZ : REM CLOSES ALL FILES ON DEVICE 8 ONLY. UNLESS OTHER PILES 


HAVE BEEN OPENED, THIS IS EQUIVALENT TO CLOSE & MERE. 


Notes: {1] DCLOSE, like CLOSE, has the effect of compieting file processing. More 
details are given in CLOSE, but basically there are two things which may need 
to be done: one |s to remove the file details from the file table, so that further 
attempts to read or write will need the file to be reopened. This hoppens to all 
closed files. However, files for writing (as opposed to files for reading} must 
also be finalised by writing the last buffer of duta onto disk; otherwise there 
will be no record of the fast items which were to have been written; and, what 
is worse, the chaining of blocks and sectors is left incomplete. This is the reas- 
on that correct file closure is stressed, This is not important with tape, as a rule 
but should be avoided on disks used for serious data storoge. Very often, of 
course, this la not a problem: the programmer simply CLOSEs the lites' If a 
syntax error of some kind occurs, however, it may be important to close write 
files from the keyboard; DCLOSE is useful for this purpose. But note that files 
are closed if a program !s edited; in this cnse use the method in CLOSE, of 
poking the number-of-filer~open location. A CBM manual saya that (using our 
file numbering convention for the error channel) CPEN 15,9,15: CLOSE 15 will 
close ali the files currently open. Both the directory entry, showing the length 
of the file, and the Block Allocation Map, as well ag the data, are written on 
CLOSE or OCLOSE of a write fic. 


Abbreviated entry: dC 
Token: $CE (206) 


Operation: After checklag the ayntax, thin routine calla CLOSE after the polnt at 
whlen paramsters have been Input. A single file number in checked to enaury it 
jan’ zero; DCLOSE alone almply searches the table of device numbers for any 
file of the correct devices - usually the default U9 - and clones esch of these. 
{The routine la from DAIN ~ DAIO), 


ROM entry point: The kernel jump address is $FF99; this jumps to SDADT. 
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DLOAD 


BASIC 4 disk fFlle command 


PURPOSE: Loads a BASIC program (or other contiguous RAM, e.g. machine-code} 
into RAM at the same tocations from which it was saved. OLOAD unless otherwise 
stated assumes CBM disk unit #8. DLOAD is in fact virtually identical to LOAD; 
the only differences are the syntax and the fact that DLOAD validates the device 
number to ensure it ls an [REE device, so tape files for example won't DLOAD. 
See LOAD, therefore, for more about this subject. 


Syntax; DOS t+ and DOS 2+ are similar: in each case individual bytes are returned by 
the unit when it is made a talker, and these bytes are processed by BASIC 
which pokes them into memory from the start address which it also receives, 
DLOAD's syntax permits the following parameters, separated by commas, to be 
used in any order: 

{i} String or string expression in brackets. This ls the program name. 

(ii) Optional D followed by expression for 0 or 1. This is the drive number; it 
defaults to drive 0, so drive O wil! be searched for the program if this para- 
meter is omitted, tt will go on to search drive ft in this case if the file doesn't 
exist on drive 0. 

(ii) Optional unit number, U followed by expression for device number 4-21. 


Modes: The action of thie command when calied from within a program differs from that 
in direct mode; the difference is identical to that for LOAD, q.v. See note [2] 
on this page. 


Examples: BASIC 4. All the following examples assume that the diskette is correctly 
initialised; this may or may not be an automatic function, 


DLOAD “MYe" :REM LOAD 1ST PROG. FROM DG WHOSE NAME STAATS 'MY' 
100 DLOAD (X$ + .COPY),US:REM LOADS THE COMPUTED FILZNAWE 
DLOAD "PHOGRAM",D1 :REM LOADS ‘PROGRAM‘ FROM DRIVE 2 


BASIC<4. The following are exact equivalents. I've assumed device & throughout: 


LOAD “:M¥*",8 
300 LOAD ': X$"+".COPY",& 
LOAO “1: PROCRAM",6 


In each case, if the file isn't found. the disk error channel will return error 62, ?FILE 
NOT FOUND ERROR. 
DOS SUPPORT (UNIVERSAL WEDGE). The slash symbol (/) is equivalent to 
; the up arrow (4) to DEGAD and KUN. So. for example, 
he :REM LOADS & RUNS 18T PILE ON DRIVE @ (ERROR IF IT’S DATA!) 
faye !REM LOADS FIAST PROGRAM STARTING ‘MY' PROM DRIVE 1. 
TL: PROGRAM :REM LOADS ‘PROGRAM’ FROM DRIVE 1, THEN RUNS 1T 


Notes: {1] BASIC 4 forces di"*(RETURN Jrun[RETURN] into the keyboard queue ff the 
Shift-stop key in pressed. Thia Is quile cnay te do when editing the screen, and 
acta bike dicad "*". thea run, This will erase your current program If you are 
uning BASIC, See Chupter 17 for remedies. 


{2} On DLOAD, a program is re-run from the beginning, retalning Its variables. 
How can machine-code be loaded? ‘Suppose we have saved 'OLD' on disk and wish 
to load §t from a program: 0 DLOAD “OLD” londs the routine, but then atarts the 
program over again; so the program keeps jonding OLD untl! Stop puts tt cut of 
itn misery, However, ainee the variables are cetnined, this construction may oF 

used, provided the machine code dovin't change variables! values; 


OKa keh 
1 IF Xai THEN DLOAD “SCAEEN” :REM LOADA INTO HAONO ff 


2 UF Kea THEY PLOAD "OLD" :RKM LOADS GN SECOND RUN 
3 CONTINGR FROM HEART ° 


{3) The DOS Interfocs [a Drive number:command string with secondary address 
eera, Tha program In note [4] to CATALOG & DIRECTORY Hlustrutes thle, 


Abbreviated entry: dL Token; $D6 (Zid) 
Operation: Apart from some nyniax chneaing, ULOAD In idanileal ta LOAD: aee Ch.5. 
ROM entry point: The kernel jump addrase is SFPDt; (hia pumps to SUKIA. 





n 
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DOPEN 


BASIC & disk file command 


PURPOSE: Opens a file, entering its parameters in tables, and sends a message to an 
{EEE device on the bus to set up its buffer. Only sequential or relative files may 
be opened for write with DOPEN; but any file (SEQ, REL, PRG,USR) may be 
opened for read. Unless otherwise stated, device #8 Is assumed. This command 
is very similar to OPEN, except for syntactical differences, the restriction of the 
device number to 4 or more, and limitations on file types. See OPEN. 


Syntax: DOS t+ and DOS 2+ differ considerably: the first will not, and the second will, 
accept commands to set up relative files. Apart from this difference, the disks 
are not very different. However, DOPEN only sends a subset of the commands 
available from OPEN: In particular, USR and PRG files cannot be mentioned-not 
that they sre vsed much anyway. For this reason OPEN can still be useful even 
when BASIC 4 is fitted. Note that DOS Support has no short form of OPEN. 

, The syntax is fairly complex: the following parameters appear in any order:- 

(i) #, then expression, which is the logical file number. This must be 1-255, 

Gi) String or string expression in brackets, which is the mame of the file to be 
OPENed. This has a maximum length of 16 - unless the open-with-replace 
option Is used, when it begins with '@’ and may be 17 characters long. In 
this case a fite of the same name is overwritten without causing error 63, 
?FILE EXISTS. See e.g. SAVE for warnings about this function. 

(ili) Optional D followed by expression for 0 or 1. This is the drive number. 

{iv) Optionat unit number, denoted by ON U or ,U with expression for 4-31, 

(v) Optional file type parameter. This may be one of:L then expression for 1- 
254; this is the relative file record length parameter, and write is assumed. 
Or: W atone, which indicates write, but to a sequential file. Parameters like 
8,R,P and so on are not accepted. The table should make this clear; 


pe, Signification ot . 
Open relative fife for write te diskette 





Open sequential file for write to diskette 
Open relative, sequential, program or 
user file for read onl 





Finally, when writing to disk is involved, remember that @ logical file number of 
1-127 sends carrivge return after PRINT# ..: while higher file numbers send 
- earriage return plus line feed. : 


Examples: BASIC 4. The DOS interface has three forms, exemplified by: 
‘LiFILE’, ‘LiFILE,W" and '2:PILE,L,100'. The third will not work with J040 or 
2040 drives, and usually causes “file not found error, These three types are ex- 
emplified, as they appear in GASIC, by these commands:- 
DOPEN#S, “OLD DATA" :REM OPEN FILE - COULD BE REL,SEQ,PRC, USAR ~ FOR READ 
DOPEN#O , “NEW DATA",W :REM OPEN ‘NEW DATA’ AS A SEQUENTIAL FIL® FOR WRITE 
DOPEN#T, “REL DATA", L87: AEM OPEN NEW RELATIVE FILE FOH WRITE. REC,LEN, »B7 


All these assume drive zero, unit eight. Most practical examples will look ilke 
them, but for compietencss we may add the following examples: 


DOPEN#A,"GNEW REL PILE", L55,0(%) ON UC¥): REM WRITK A MEW RELATIVE FILE, 
WITH REC.LEM, 65, OM DRIVE X OF UNIT Y¥ 
DOPEN#D, "'#” REM OPEM CHANNEL FOR DIRECT ACCESS TO DISK 


The fleut of these final two examples opens topical file number 8 to a new reint- 
Ive fite, which, when ff writes, will replace the previous Elle af the same name, 
If there is one, The recerd length {4 55; this Ineludes the carriage return char- 
hetor at the ond of cach revord, The drive and unit numbers are expressed aa 
variibles, and aro therefore controllod by the rest of the program, TSYNTAX 
ERHOR whit appear, of courw:, if they ure not wilhin thelr alletted rmnges. 


Tho lost exanypte opens a ‘diceet uccesa' channci to a disk. so that lracka and 
xeclors may be written and read without the Intervention of DOS. These ean lit 
very useful, although they one not weil documentud and not particularty easy to 
Use, 
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BASIC<4, The following OPEN ststements are exactly equivalent to the DOPEN 
gintements which we've just examined, Note especially the format to be used to 
open a relative file without DOPEN;: the parameter must be sent as a single byte 
to simulate DOPEN.* 


OPEN?S,8,5,"0:0LD OATA,SEQ, READ” :REM OR OPEN 5,8,5,'°0:0LD DATA,5,R" &€ 
or OPEN 5,4,5,”0:0LD DATA, P&G, READ” 
or OPEN 5,8,5,"0:OLD DATA, USER, READ” 
Note that OPEN 3,8,5,"0:OLD DATA,REL,R£AD” is accepted only by DOS 2+, The 
secondary address 5 has no particular significance. BASIC 4 generates its own 
from a table. Secondary addresses of 0,1, and 15 are, of course, already re- 
served for other purposes. 


OPEN"G, 8,6, "0: NEW BATA, SEQ, WRITE": REM OR OPEN 6,6,6,"0:NEW DATA,S,8" 6C 
OPEN 7,8,7,"O:REL DATA,L” + CHRS$(87>* 


Again, this latter form can only work if the disk is fitted with DOS 2, DOS 2.1, 
or DOS 2.5; what I've loosely referred to as DOS 2+. The parameter for the 
record’s length must be within the range 1-254. in BASIC 4 this is checked by 
DOPEN's syntax, but here it is the prograaimer’s job to keep the parameter ln 
acceptable limits. 


OPEN B,Y,4,X$ + "@NEY REL PILE,L" + CHR$(55) 
Where Y is the device number. and X$ is assumed to be either "6" or 1". 


OPEN 9,8,9,“#" 


This is an example of a file opened for direct access to the disk unit: now, 
PRINT #9 is fottowed by commands of the B-W and M-E type (q.¥.) This is a- 
user file and it might be expected that a name could be assigned ta it when it 
is opened, but this seems never to be done in practice 


Notes: [t] There is not space here for ful} demonstration programs to open files/ write 
to them/ close/ read back. These in any case involve many of the functions of 
DOS, such as RECORD, DCLOSE, SCRATCH and so on. Chapter 6 has a set of 
disk file demonstration programs which illustrate the possible permutations and 
combinations of the CIM disk drives. 


[2] Relative files, opened for write, are treated differently from sequentinl files. 
The latter, roughly speuking. are allocated 4 buffer and identification on the 
eatatog, and are written as the need arises, 80 that if several are written at one 
time their sectors will interweave in a leapfrog-like manner. Relative files need 
an Indexing system, On DOPEN or OPEN a buffer hag to be allocated for the 
side sectors as well os the main file. Now, If RECORD # file-number, 200 is 
executed by BASIC. the entire file must be generated for 200 records. in this 
way the file may be creuted in a more orderly fashion than is possible with ; 
yequential files. This may reduce disk rend errors, since tha read head hus tae 
fewer track and sector skips (on average). 


(3] A complete list of interface commands available through OPEN can only be . 
made by disassembling each DOS. There are certainly more than uppeur in CBM 
dogumentation. Mike Todd (in [PUG, July ‘81) suya that opening a requentint fe 
for read, whlle it ia belng written, using something like OPEN 6,8,4,"FILE,N" 4 
enables the file to be rend Sack, or at Teast Ws buffers, Harry Broomhall foun 

4 command using '&' which may ba weed an a dlignostic routine - if you know how: 


Abbrevisted entry: dU Token: $CD (205) 


Operation; Chapter 15 and Chapter 5 outline the workinws of DOPEN and QPEN so fat 
as HASIC goes. The other work In performed by the «isk unite themselves. 


ROM entry point: The kernct jump nddreas iy $FFG6; this jumps to 31942 


ae epi se, — 





ince fe ee Os tan ite 
¢Thie ls nut the ouly example uf undocumented CHM ~functiona which usp wa parameter of 
thle type, Some CUM printera can only bn made ty perform cortain functions when @ 
byte parameter is anni in thla way, aqme 
‘there's « serious bug 16 UPRN which shows ttael? Uf the drive number te omilte 

in sloppy programing, of quurse}. The cata dafault ta differant from the director? 
default, #9 deta te written to the wrong disk unit! [lence all the drive numbare. 
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DS$ & DS 


BASIC 4 reserved variables 


PURPOSE: provides a record of the status of the disk system after any operation. 
fn this way an error condition can be noted without stopping BASIC. The 
variables OS and DS$ are reset on being read. These extra variables are purt ot 
the price paid for having an external DOS. [f DOS were accessitde to BASIC,ST 
could record all status conditions, although not im its present form with only 8 
values at most. However, in fact it must be read from the disk drive like other 
data. ST is still needed to convey information like ?device not present, while DSS 
stores information obout the results of disk handling. Errors can range from the 
gross, when for example no diskette is found, or a blank disk can‘t be read, to 
the subtle, such as a failure to exactly match a file name. These are not serious 
errors; in fact, they show that the system is working correctly. Hard errors, on 
the other hand, such as mistakes in the internal checking system of a sector, 
may be serious. 


Syntax: DOS t+ and DOS 2+ both treat DS and DS$ in the same way; in each case the 
variable is read from disk through the command/ error channel with secondary 
address 15. However, the variable is only recognized as DS or DSS by BASIC 4 
or some toolkit-enhunced BASIC<4 variations (notably Disk-0-Pro). Otherwise it 
is input? and any convenient name may be given to the variable(s). Like TI and 
ST, DS and DS$ are not variables in the normal sense; they are not stored in 
RAM with other variables, but instead are computed when they are asked for. 
Statements like DS<5 or DS$="HIt" are specifically filtered out by LET, but the 
either variable may be printed or compared: . . 

7083 

IF DS>19 THEN PRINT DS$: STOP 
DS at present may take values below 75; not all are used, some perhaps have 
been reconsidered, others (e.g. 2-19) never ttsed. 
DS$ has the format ‘Error number,message, track sector’ where the latter two 
varlablea may be irrelevant and set to zero. ‘0,ak,0.0' , '2l,rgad error,i8,01' 
'S0.record not present, 24,7' are typical disk status messages. 


Examples: BASIC 4. This, lke the other examples, assumes the error channel ig open, 
[f It Tan, OPEN 15,3,15 wil] open it - the file number may be different, the dev- 
ice moy not be 8, but the secondary address must be 15. 
PRINT DS$: REM PRINT PULL MESSAGE WITH FOUR PARAMETERS 
IF D9>19 THEN GOSUB 10000: REM GO TO AN EAAOR-HANDLING ROUTINE. 


BASIC<4, If WOS Support isn't loaded, the following can be used: 
1000 INPUT#15,EN, EM$,ET, ES 
1010 IF ZN>19 THEN PRINT EN *," EMS "," ET “," ES: CLOSE1: CLOSE 15 
1020 RETURN = 


If a program crashes with a disk error, the error channel may need to be read 
in direct mode. The eugiest entry la 
oP15,8,15: 1N15,0,0$; ?¢,0$: rem only bother with wajor variabies 


DOS SUPPORT (UNIVERSAL WEDGE). All that ts needed, provided the error 
channel ts open, is 


@ or ». 


Notas: [1} The problem with this varlnble is when to use ft, like ST. DS could be 
checked after uvery disk operation, but the drives won't usunlly Indicate errora 
if a» gout progeam is sunning, A program which crashes, und leaves the red LIP” 
In the contre of the drive on, is an obviaus candidate for dlrectly rending DS: 
to find out what went wrong (and turn off the LED). Programs which INPOT# 
date can afford to iest DS after each field la rend; but can progrums which ut 
GET#? Thers iv no general answer to thin questlon: it depends on the dagren of 
accurity which tho system requires, [It may alsa depend on such) hardware factors 
aa the age of the system, Ite wtnte of maintenance, and the quality of the diska. 
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12] Ath BASIC 4's keywords for disk handling clear DS$, DS and ST. The rout- 
ine to do this, at $DBE2, is called whenever the command string buffer is fited 
prior to transmission on the IEEE bus. To read O5$, a routine at #D991L or 
$0995 ls catled, depending on whether the string is being fetched or re-fetched. 
It's read one byte at a time until a carriage return character is encountered, 
after making the disk a Talker on secondary address 15. The string ts poked 
into RAM at the low end of the strings, and pointed to by (SOE), with length 
parameter in $0D. From here it can be printed. This process avoids any prob- 
lems assovinted with inpuiting strings containing commas, DS is evaluated by 
converting the first characters up to the first comma into a numeral in a floating 
point accumulator. (In fact Disk-0-Pro evaluates this string and stores it after 
all disk operations, so it more closely resembies a normal variable). Some pre- 
BASIC 4 programs use DS and/or DS$, unaware of the promotion in store for 
these variables, and these programs will crash when they meet statements like 
40 INPUT "SIZE OF DIRECTORY"; DS$: DS=vaAL(DS$) if they are run on a BASIC 4 
machine. DS and DS$ can be set up. like TI and ST, as ordinary variables by 
poking, but this is e trick of little practical value. 


(3] The table summarises the important features of disk status messages. 






























Information 
{not an errar} 


0 Everything OK 
1 Files scratched 
(gives number) 
2-19 Undocum- 
ented, Not 
important. 


Programming mistake or 
simple mechanical error 














20 Sector header not found 
21 Syne mark not found 
22 Sector not found 






































Ouiaul 23 Checksum error in byte 
Errors 24 Byte read error 
lat 25 Readback compare error 
Disk 26 Write protect tab on” 
| Level 27 Checksum error in heade 
| 28 Next sync mark not found 
Mnittion 29 Disk 1.d./BAM mismatch? ; 
30 Syntax error 
Syntax 31 Unrecognised command 
Errors 32 Overlength command 
33 Wrongly used ? or * in name 
34 File name omitted 
_  }89 Unrec. command to channel 15 
Relative | 50 Expand rel.|50 Reading past end of file 
and file size SL Relative record too long 
Seq. Relative file too big for disk 
Files 
60 Attempt to read a write file 
File §1 File not open 
Errore €2 File doesn't exist 
83 Fite does exist 
64 File type mismatch 
65 Block-Allscnte error; gives 
Track & next avulladie track & nuctor 
Sector 68 Track or aector out of range. 
Errors 67 System track or sactor error 
70 Chonnol to disk unavailable 
DOs TL Error in BAM? 
Errore 72 Disk (or directory) full 










73 BOS mismatch! 









A050 drly 


*) Theaa may lend to problema Jater. Sen Chapter 8 on write-prutect taba on CUM dinh® 
and on DOS Incompntibititton. ! Genaralty ro-initlailsation ba required, 
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DSAVE 


BASIC 4 disk file command 
PURPOSE: Writes a consecutive block of RAM bytes to CBM disk, usually a BASIC 


program, and updates the directory so the RAM dump is retrievable. DSAVE is 
similar to SAVE in most respects. 


Syntax: DOS Te and DOS 2+ use the same DOS interface for SAVE. This is simply the 


Examp 


Notes: 


Abbrevlatad entry: dS 


Opera 


drive number foltowed by the file name. An additional feature is the optional 

leading @ before the file name, producing the much-discussed ‘save-with-replace’, 

DSAVE uses the following parameters, in any order. separated by commas: 

(i) String or string expression in brackets. This is the file name. 

(ti) Optional D followed by expression for 0 or 1, This is the drive number. The 
default value is drive 6. 

(iii) Optional U followed by expression for 4-31. This is the IEEE device number. 
Its default is 8. 

A null name ("") js not accepted; the name string must have length>d, even if 

it ig only CHR$(9)! 


les: BASIC 4. The examples are typical DSAVEs. Usually this command is used 
in direct mode to save a new or rewritten SASIC program, but it may be used 
within BASIC sometimes: see note [2]. 

DSAVE “BASIC PROGRAM" :REM SAYES ONTO RICHT-HAND DRIVE, ORIVE 0. 

DSAVE “@BASIC PROGRAM", DL 

DSAVE DI, (X$) ON Ud 
If the program exists, DS$ signais error 63, unless save-with-replace {the second 
example) bypasses this test. The usual maximum Jength restriction holds: BASIC 
checks the name, ensuring 16 characters maximum. (More than 16 characters can 
be sent to the device by avoiding this test). 


BASIC<4. The commands corresponding to the previous three examptes are: 
SAVE "0; BASIC PROGRAK”, 8 

BAVE “1:@®BASIC PROGRAM", 8 

SAVE "1:" « X$,8 
DOS Support provides no short form of SAVE. 


{1] Save-with-replace. The remarks made in Chapter 5 on SAVE apply also to 
DSAVE. A fairly early manual mentions error 47 in DS (this ia ‘system track or 
sector error’) as s possible result of DSAVE "@...". It seems best to avoid the 
construction with 

SCRATCH "BASIC PROGRAM" ,DL: DSAVYE “BASIC PROGRAM", D1 


{2] SAVE and DSAVE dump RAM from pointers ($28) to ($2A) or, with the old 
BASIC 1, from (STA) to (57C). The very last byte is not saved. The machine 
eode monitor relies on this to save different areas of RAM. In fact it is easy to 
save from BASIC, using only a few pokes to reset the ‘start of BASIC’ and ‘end 
of BASIC! to new values, and repoke them to the true valves after saving your 
data. The following example shows how a screen can he saved; in future, when 
it Is loaded, its contents will replace whatever was present on the screen. This 
ean be useful in demonstrations, graphics, and so on, 

57000 PL=PEEE(42}:; PH=PEEK(43): REM STORE END-OP-BASIC POINTERS FOR BASIC>1 

$7010 PONE 40,0: POXE 41,128: POE 42,0: POK® 43,136: REM OR 1232 IF 40COLS 

57020 DSAVE "SCREEN PIC™ :REM OR SAVE “O: SCREEN PIC", & 

$7030 PORE 40,1: POKER 41,4: POKE 42,PL: POKE 43,PH : REM RESHT POTNTERS 

$7040 RETURS 
Now, drive zero haw ‘SCREEN PIC' stored on Its disk, [n direct mode, DLOAD or 
LOAD wif put it straight into the screen. In progrum mode, you'll neerl xomething 
like this (see DLUOAD and LOAD for the reason): 

0 ON KX GOTO 400,600,1800,.. 

990 Xa3: OLOAD “SCREEN PIC", DO 

1000 RYM CONTINUE HERE WHEN ‘ACAREN PIC' [3 LOADED AND PROURAK RESTARTS 


Token: $D5 (213) 
tlon; Chapter 15 and Chapter § undar SAVE dincuss thin command, 


ROM entry polnt: The kernel jump addreas ls SFFAE; thie jumps to sDROD. 


. 
P 
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HEADER 


BASIC 4 disk system command 


PURPOSE: HEADER (or NEW) formats a blank disk which then becomes usable for any 
CBM disk operation. it allows a name to be given to the disk, and a two- 
character identifier, There is an alternative short form which erases @ disk’s 
directory and enables the disk to be renamed, but does not change the identifier 
NEW as @ disk command - not the same as BASIC NEW - is the BASIC<4 version 
of HEADER. 


Syntax: DOS 1¢ and DOS 2+ have identical DOS interfaces for this command: 
'N Di:Fl (,D0]' where N or NEW signels the command, D1 end Fi are drive num- 
ber and header name respectively, and DO is the optional identifier. Although 
the interfaces are identical, they are processed differently, or so the document- 
ation says, BASIC 4 has several differences compared with earlier BASICs; the 
syntax is different, the cautionary ARE YOU SURE? message prevents accidental 
disk erasure, end ?BAD DISK ERROR appears if, after the disk unit is finished, 
DS exceeds 1. This is checked within the BASIC 4 ROM. 


READER uses the following paraineters in any order, separated by commas: 

(i) String or string expression in brackets; this is the header name, and it is 

checked to ensure that it doesn't exceed 16 characters. 

(i) D with expression for 0 or 1, This drive parameter is compulsory. 

{lii) Optional 2-character identifier. This is entered as I follawed by the two 
characters (e.g. Al or #6 or $a or zz atc.). Note that these two characters 
are stored in $033F and $0340 and could be poked in if a modified HEADER 
command were used. The characters are simply read directly by BASIC, So 
I (X$) or (4, or I, where the syntax is variously wrong, yieid i.d.a of 
(X and 4, and , in order. 

(iv) Optional unit number. U followed by an expression which evaluates to 4-31. 


Examples: BASIC 4. The first is a ‘long’, the second a ‘short’, header or new. 
READER D 1, IRW, "PRICE LIST PROGS" 
AERADER 00, "EXPERIMENTS" 
HEADER (X$), DI ,Ud REM LEN(X$) MUST BE >0 AND <17 
The final example shows how a string expression is used. 


BASIC<4, Exact equivalents are given, omitting the BASIC 4 keyword tHEADER': 
PRINT#15, “NEWL: PRICE LIST PROGS,RW’,8: REM ANY ALPHABETICS OR, £G NOUGAT 
PRINT#15, "NO: EXPERIMENTS”, & 

PRINT#15, "KL:" + X$,9 

In this case, ARE YOU SURE? won't appear and DS or DSS must be read by the 

programmer if sumething seems amiss. The system won't do it for you. 


Notes: [1] tf HEADER or NEW showa an error, read DS to eatablish the cause. it may 
be something as trivial as a missing disk. Or it may be that the disk is of poor 
quality, or a write-protect tah may be in place. There is a potential riak in this 
situation that other disks wil he partly ernscd: see Chapter 6 on write-protect 
tabs for example. [f the disk won't be fortiutted switeh off before using other 
dinkettes if you wish te be certain that they won't be corrupted. 


{2} The whocter version In fuster: say 45 seconds agninst several minutes, dep- 
ending on the DOS. Note that pitrt of the directory is cleared, but the files all 
romain on disk without their pointers, a situstlon rather Ike BASIC NEW wher a 
BASIC program In ‘ernsed'. Issue 10 of Compute! CDisk Fie itecavery Program, 
by David L. Cone) has a program ta minke dala recovery paisitle, 


13) After HFADER put DOS Support {or any other program which you would Uke 
te be the first to load) on the disk before other programs, 


[4] SDAY9E (56222) prints ARE YOU SURK? and expects vilher Y or YES Cunahift 
ed, with no Apaces) and clenew carry if lt finds it. Not vary usable from BASIC. 


Abbreviated entry: hk Token: $00 ¢208) 


Operation: See Chupter 15 for tha BASIC ROM processing. 
ROM entry point: The kernel jump address la SF eF, thin jumps to #29N2, 
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INITIALISE 


Disk system command unavailable directly in BASIC & 


PURPOSE: Causes the disk unit to read the directory and the block allocation map 
(BAM} from a diskette in drive 0 or } or doth, This operation may be performed 
in direct mode - when starting up, for example - or in program mode. It is not 
needed usually in drives fitted with DOS 2+, 


NOTE: Some disk systems (e.g. Apple/{fT 2020) use the some command INITIAL~ 
{SE to format a diskette, an operction called HEADER or disk NEW in the COM 
system, INITIALISE will not domoge the dota on a C&M disk; it will erase it fram 
on Apple/iTT disk. 


Syntax: DOS 1+ and DOS 2+ all recognize this command and employ the same DOS 
interface 'I [,DO}', 8050 units, sensibly, perform this as a hardware feature, 
go disks cannot be sneakily changed without initialisation, 4040 units don't have 
this feature; instead DOS checks, before some operations, that the disk i.d. 

* matches the disk in the drive. See note {1). 


The syntax is PRINT#5,"I1 (,0 or 1}" or PRINT#i5,string expression which 
evaluates to “f [.0 or 1)". 


Modes: Direct and program modes are toth accepted. 


Examples : oP 15,6,15: pRi5,%1": 20 "*",8 :rem do this on switching on. 


This ts the short form of OPEN i5,8,15: PRINT#15,"I": LOAD “*",6 and may be used 
with any BASIC/DOS combination to initialise two disks, then load the first pro- | 
gram from drive 0 into RAM. i've assumed device #4. Shift-Stop with BASIC 4 
will {oad and run the same first program. ft uses DLOAD “*", 


PRINT#15, "19" and 
PRINT#15, "11" 
Initialise disks in drive $f and drive 1 respectively (provided channel 15 is open). 


DOS SUPPORT (UNIVERSAL WEDGE). PRINT#15 ia performed by this wedge, so 
@I1 or of 
@Ig or 719 
@llor oF! 

may be used in direct mode to initiallse both disks, drive 6, or drive 1. 

. Programs running disks equipped with DOS i+ need to initiallse new disks put in 
the drives; and 4040 disk units will need this too for disk operations which do 
Not read the directory (see note [1]), Either type of routine is satisfactory:- 

100 INPUT "DRIVE"; D$: D$="i"sD$: PRINT#L5, DY : REN ZACLUDES VALIDATION 
100 PRINT#L5S, "19" 


Notes: (1) After initialisation, the diak read/write head is left positioned over the dlr- 
ectory track (18 or 39 in the 8050), ready to read/write to sectors of the diski 
this central position is used to cut down head sevking time, If a disk hasn't been 
initialised the DS$ error mesyage will read DISK ID MISMATCII (error 29). This 
ts true unless the disk has the snine i.d, as the HAM, but nevertheless was not 
the disk initlalised, in which cuse data will simply overwrite the disk now in 
place, becunac DOS cannot tell that {t hay changed. For thla reason strong warn: 
ings are often made of the disnsters which may happen if disk i.d.s aren't 
farefully selected to be different. Similarly, backup disks should be trented with 
core, stored, perhaps, In another place. Automatic initintisation of 4040 disk 
unita ts net invoked by KHACKUP, COLLECT, HEADER, or RECORD, or any 
Hrect aecese command, To be on the sufe side, therefore, Inithlisation, using 
the format avove, may well be carried out before these commands ere used; for 
example, COLLECT on a wrong disk may scramble up data. 


12) A COM manual gives this methad for turning off auto-initinllsatlon, apparent- 
ly for 4UA0 dlaks: PRINT#LS, “M-8" CHA$(243) CHRG(16) CHRS(T) CHR$CL) 
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RECORD 


BASIC 4 relative file command 


PURPOSE: Positions the relative fite pointer to the start of any record within the 
relative file, or to any byte position within a record. This command is unusable 
with sequential fies, and works with DOS 2+ only, not DOS t+, It may be 
Bimulated by BASIC<2, provided this BASIC runs DOS 2+ diska. 


Syntax: DOS 1+ has no relative file facility, unless specially written dlrect accesg 
commands are used, DOS 2+ accepts RECORD; the DOS interface is 
P sec. address byte record no. low then high byte position within record. 
AS on exampie, the String "P"+CHR4$(5}+CHR§(9)+*CHP$(0)+CHR$(1) sent with 
PRINT#IS to the disk positions the pointer to the relative fite opened with sec- 
ondary address 5 at the first byte of record 9. The syntax of RECORD is less 
baffling. Unlike most other BASIC DOS communds the order of its parameters 
is invariable. The syntax is; 
RECORD # expression for logical file Q-255), expression for record number 
(865535) (, optionai expression for byte within the record (1-254)], 
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if the byte parameter is omitted, the value 1 Is assumed by default, 


Examples: BASIC 4. The short illustrative program opens a relative file and writes ten 
records into it. See Chapter 6 for a lonyer example. Note that the records are 
shorter than their permissible length. This is possibie because the starting point 
of every record is computed by the system, and because a record, as it is 
written to disk, is terminated by Return. On Teading back. by INPUT# for 
example, the record is read until the next Return is encountered, so the lack of 
data at the end of the record has no effect. There is one proviso, however - 
RECORD must be issued before each PRINT# statement, to move the pointer to 
the required record, [f this isn't done ~ try renumbering Hine 30 ag line 15 - 
the records may be written consecutively. This could be a useful feature, but 
appears to be unretiable. it's safer to use RECORD wilh the byte parameter. 


19 depen #1,“random file’,140 -:rem length parameter iaplies open for write 
20 for j= 1 te 10 
30 record #1, (j} 
40 print #1,"abcdet" + str$ij} 
$0 next: delose #t 
I have omitted references to DS$ from thle program. If it is checked after line 
30, it will return status message §0, 'record not present’, showing thut the file 
Is being expanded. As an example of the byte parameter, run this program too: 
10 dopen #1,"random file” :rom open for raad, by default 
20 for j = 2 to 10 
30 record #1,(11+3),4 ‘rem read records in order 10-1 starting at4 
40 input#l,x9: print x$: next: dclase@l 
This prints daf 10 then def 9 then def A... 


BASIC<4, The equivalent programs are as follows, avoiding BASIC 4 keywords: 
O OPEN 1,5,5,"0: RANDOM FILE,L," +CHR$(40) 
~O0 FOR J = t TO 10 
30 PRINT#I5,"P" + CHRS(S) » CHR9(J} + CHRS(P) + CHR$(1): REMEMBER CHANNEL iS! 
40 PRINT#1, "ABCDRE” + STRS(J) 
SO MEAT: CLOSE 1 i 


10 OPEN 1,8,5,0: RANDOM FILE" -:REM READ ASSUMED 

20 FOR J =< i To 16 

30 PRENTHIB, "P™ + CHRICS) + CHRS$(11-4) # CHRS(O) » CHR$C4) 
40 INPUT#1,X$: PRINT X%: NEXT: CLOSE 1 


Notes: (1]'Error’sOla generated whenever a relative file fa expanded beyond its 
currently nilocated dimith., If INPUT# utlempts to read heyond thexu Hmita, the 
same Menange Appears, ane ST {x act to 64, HASIC returng curriage return, 


\bbreviated entry: reC Token: $CF (207) 
Iperation: fee Chapter iS (BASIC 4 referencia from SOTAF), 
(OM entry point: The kernel jump addrosa in $FF9C; thia jumps to SD7A4F, 
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RENAME 


BASIC disk fife command 
d. If the 
PURPOSE: Changes the name of a disk file. Any type of file may be rename: 
new name selected is already present on the diskette, DOS generates error 63, 
file exists. 
i OS interface 
ntax: DOS 1+ and DOS 2+ each have this command. in each case the D 
~ aes identical: 'R D1:F2 = D1:Fi' where Fl and F2 are the old and new names, ane 
Di is the code for whichever drive the file is on, The internal operation of each 
DOS may be different. Certainly Harry Broomhall*detected errors in DOS lin 
which seratched entries in the directory made RENAME (or to be precise 
PRINT#15,°R ...7) faii to work. Like COPY, this operation has the odd feature 
of having its parameters reversed in its two versions. 
i i by colons: 
RENAME has the foliowing parameters in any order separated 
(i) Two strings, or string expressions in brackets, separated by TO. These of 


course are the before-and-after file names. ' ; 
Gi) Optional D with an expression for # or 1. This is the drive number; the 


default is drive 9. . : 
(iii) Optional U with expression for 4-31. This is the device number, ita default 


value is &. 
: GPYing a file to 
E les: BASIC 4. A couple of typical RENAMES follow. Note that Cc : 
en ha same drive ~ if there's space for it - or to another drive, then scratching 
the original and recopying the file back if it's now on another disk, has the 
same effect as RENAME. 
RENANE D1,"OLD NAME” TO “WEW NAME” 
RENAME (X$} TO (Y$) 
1G00 rename ("file” + etr$(x)} to ("flie” + etr$(x+1)) 


i i i ber after 
The final example shows how a file's name can reflect a version num ; 
being ipdatad. for example, so that its current standing or historical statua is 
easy to see. A date or some other meaningful numbers or letters can be used 


in the same general way. 


i i he three just 
BASIC<4, The examples which follow are Identical in effect to ¢ 1 
printed, but don’t use the BASIC 4 keyword. They will therefore work with any 
DOS and any disk (subject to possible bugs ... sea nate above, and note [1]}. 


PRINT#15, "RENAME1L: NEW NAME=OLD NAME” :REM NOTE THE ORDER! 


PRUNT#L5S, "RO: + ¥$o+ “a" + KF 
1000 PRINT#15,"REN@:" * "FILE + STRE{XoL) + “e+ “PILE” + STRS(X) 


Notes: [1] This doesn't work wlth unclosed files. They should be closed in any case. 
Abbreviated entry: reN 


Token: $D8 (216) 
Operation: Apart from the syntax check thls la curried out entirely by DOS. 


ROM entry point: The kernel jump table address ‘a $FFB7; from here the routine 
jumps to $DB55. 


“Warry Broomhall {of Heronview Ltd) tm @ ‘Britian authority on the CDM and ita disuse 
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CRATCH 


ASIC 4 disk file command 


JRPOSE: Deletes one or more files from disk. CBM’s pattern matching sequence may 
be used - with caution - to stratch several files. D5$ returns DS=1 followed by 
files scratched' and a parameter showing the number of files which have been 
geratched, 'Seratch’ is a word peculiar te Commodore; most systems ‘erase’ or 
‘delete’ files. 


mtax: DOS 1+ and OOS 2+ use the same DOS interface. BASIC 4 however only sends 

a subset of the possible command string, namely ‘§ D1:Fl' where § signifies 

SCRATCH, Dl is a drive number and Fi a file name. As the examples in BASIC 

<4 demonstrate, more elaborate constructiuns may be used. The penalty for 

making a mistake is high - a seratched file is not easy to recover, 

SCRATCH uses the following parameters in any order separated by commas: 

(i) String, or string expression in brackets. This is the ‘name string’; often 
aimply a name, it may include * and/or ? symbols, and thus be treated as 
a string holding pattern-matching symbols. 

Gil) Optional drive number, D followed by an expression for 0 or 1. This 
defaults to drive 0. 

Gii) Optional unit number, U followed by an expression for 4-31. This defaults 
to unit number 8. 


Note that scratch prints ARE YOU SURE? and expects Y or YES, in direct mode. 


Like HEADER. when culled from a program, this question-and-answer precaution 
Is omitted. After SCRATCH, and again only in direct mode, DS$ is read, and 
if it is mot null (i.e. if some files actually were scratched) printed out, as for 
example O1, FILES SCRATCHED,03,90 when 3 files were scratched. This same 
sequence of messages is obtainable from BASIC<4, but must be input from the 
error channel manually. 


Finally, note that there ls no warning if a file to be scratched doesn't exist. If 
its name was misspelt it'll stl be there. 


xamples: BASIC 4, These examples are, I hope, self-explanatory. Note the program 
example; this is the way ta avoid dopen "@test",125. 
SCRATCH “PIND CHECKLETTER",01:9EM SCRATCHES A PROGRAM (OR COULD BE DATA) 
SCRATCH 00,"DIS*" {REM SCRATCH ALL STARTING ‘DIS‘ 


scratch d0,"*" us trem scratch all on drive @ of unit @ 


100 scratch "test file",d1 
110 dopen "test file”, d1,125 


BASIC<4. The equivalents to BASIC 4 follow, There's an extra example to show 
the extended syntax possible with this version of the command, 
PRINT#15, “SCRATCH : FIND CHECKLETTER” 
PRIWT#15,°S0:DI9"" . 
PRINT#18, 50: *" 
100 PRINT#15, "SCRL: TEST FLLE" 
110 OPEN 1,8,6,"L:TEST FILE,L,“ + CHR$(25) 


PRINT#1S, "$1: TEST, 1:MC.OLD, 9: X~PILES, @: TESTER” :REM MULTIPLE DELETZS 


jotes: (1] Files currently open, or thought to be open, aren't acratched. COPY ta said 
to have the effect of using Internal channels an that SCRATCH bellevea the file to 
be open, and leaves It. [t can be scratched later. 


(2] Don't seratch unclosed fites: COLLECT or VALIDATE the diak. Otherwiye the 
lust existing sector will not point to a sector with a zero termination byte, and this 
sector may apparently connect with another (lig, no DOS will scratch parts of thet 
too. Suppose a sequential filo, writing to disk, signain ‘disk full’; Ita direetary Is 
marked '*' an unclonad. SCRATCH ow replaces this with file type DEL, and wil! 
probably produce strange effects. But COLLECT in flag, or reed and write back 
with CLOSE if tho data is valuable. Or ?xyntex error nay port a write fila; ro- 
ooen channel 15, than clone aii files. Make COLLECT/ VALIDATE a cule, 


\bbreviated entry: 2C Token: SDB (217) 
10M antry point: The kernel jump address Is SFFRA; thin Jumpn to $SDARB. 


REM ASSUMES OPEN 16,9,15 TO UNIT 9 
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CHAPTER 8: OTHER PERIPHERALS AND HARDWARE 





8.1 Tape cassettes. 


Cassettes and tape recorders Commodore's tape recorders exist im three forms: built 
into the machine, in the earllest modeis; the C2N external recorder; and VIC‘'s tape 
recorder. There have been internal changes in printed circuit board construction, so 
that special load/ save routines nay not operate with every model. The CON has a short 
cable and edge-connector; power is supplied from the PET/CBM, so the device is not 
easily usable away from the computer. VIC's recorder is in white plasti¢ in place of 
the eartier black, [t is compatible with the PET/CBM and cheaper. Each PET/CBM hes 
ports for two cassettes, and a small amount of software exists which keeps files on ofie 
tape, reading and updating them onto the second. The parts ere arranged differently 
in each of the main designs; see the diagram in Chapter 1. This ts usually no problem, 
but from time to time, when switching machines, a user may be surprised to find no 
response from the machine, because he is addressing the wrong port. The recorders 
are assigned device numbers | and 2, and the whole of their operating system is in 
ROM. There are improvements in BASIC>1 over the original, but the main features are 
identical in all ROMs. Consequently external tape recorders, which are portable and 
robust, are often useful in transferring programs between machines even when they 
are equipped with disk drives, because there are few compatibility problems. The top 
of the edge-connector should be labelled; it's often possible to connect it upside-down, 
when recording won't take place. 

; All tape recorders use similar principlea: there is an erase head and a record- 
ing head, arranged so that during recording the tape is first demagnetised, then rec- 
orded. Physically, the recoding takes the form of vertically mngnetised fields on the 
tape, their form depending on the amount and frequency of the magnetic flux generat- 
ed in the recording head. On reading back, the eruse head is off and the recording 
head acts in reverse as a read head, the tape, as it passes, inducing current in it 
which is amplified. (Some machines have separate heads for recording and playback}, 
The capstan and pinchwheel drive the tape at a constant speed, the capstan rotates, 
driving both the wheel and the tape, whenever they are brought in contact by press- 
Ing 'Play'. The leading (right-hand) spool is maintained under tension, so the tape is 
tightly wound, and variations in the effective diameter of the take-up spool have no 
effect. Leaving 'Play' pressed when the recorder is off may cause the (now static) 
Capstan to dent the pinchwhee!t, and cause irregular playback, In fast forward or fast 
backward mode, the capstan is disengaged and drive applied directty to one or other 
spool. Routine recommended maintenance involves cleaning and demagnetizing: again, 
all recorders are much the same, and cleaning kits for non-computer cassettes are fine, 
consisting of cotton-wool swabs and sotvent (e.g. isopropyl alcohol) to remove tape 
debris. Demagnetizing is alwaya recommended, and sometimes carried out. The movable 
type of demagnetizer, relying on the inverse-square law to magnetize the hend in alt~ 
ernate directions with ever-decreasing flux, scem to be best. Head alignment problems 
may arise when using tapes recorded on equipment different from that used in play- 
beck. A recorder with {ts recording head not verticul will usually read back without 
difficulty, because reading exactly matches the magnetic pattern deposited on writing, 
a recording made with the same machine. If a recorder han persistent difficulty in 
loading tupea, this may be the reason. Adjusting the head {6 fuirly casy. 

. Caysette tape is cheap, portuble, and cusy to send through the port. (Some 
tape ‘magozines', o.g. ‘Cursor’, and Petaoft and Commadore crssette programs bear 
commercinl witness to thls). The dost type IM ferrle oxide (not chromlum) of reasonable 
qnallly, A screw-type casing (which can be taken apart If the tape in tangled) may be 
better than the glued type. We shath see how toe estimaie storage an tape; tho best 
length of tape depends on the user's purpose, some preferring C-10 or C-12, others 
C-46 or C-88. Avuld thie tape. In principle I's a geod idea to test tape, and a number 
of teak peograms oxist.* Unfortunately this t4 a tine consuming process, much more 
40 than wkh disks. The best compromise ia probably to test tapes to be Gued for 
madier' wlomge. Theen tips: (1) don't save useful stuff directly onto a leand- new 
ape; test it or unwind and rewind dt first to unateateh it; Ci} J omay felp te demag- 
Hetize tape, vince PET/CBM uses high recorday levets, to eraag old programs or data: 
GM) record the Great program/ date with a few seconds’ extra leader, 

"J Butterfield (e.g. CCN Sopy.'@1) and Kitabaud-Wicrucomputing (March °40) tor example. 


a 
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Commodore's newest cassettes areequipped with a tape counter; the older modela 
‘e not. Section 8.4 has information on ways around the restriction. [¢ has additional 
ateriat on fast forward winding and the possibilities of constructing tape directories. 


.2 Data Storage on CBM Tape. 


itroductlon Commodore's tape system stores data coded as square waves, The dia-~ 
ram shows, aS an example, how a byte is stored; it has a marker followed by nine 
its, the last being the parity bit. (Odd parity ia used). 

€——-Byte Marker-—3<-—Low Bit+ —High BLt—.... Parity Bit 

‘Lean 

w—@$ B84 64 52454 G4 24s S24umethdps 
here are three frequencies, which we can call short, medium and long. A byte mark~ 
p is one long wave followed by a medium wave. A bit is either a single short wave 
towed by a@ single long wave (bie 0), or vice versa (dit 1}. The periods in micro- 
sconds in the diagram were quoted in an article by M Maynard of Audiogenic Ltd. 
he actual process of record and readback is complex. So far as [ know, source code 
or the operating system has not been released, * 


ata storage with BASiC There are two types of fife available, which are exactly 
ualogous to disk files' PRG and SEQ file types. BASIC programs are held, tike mach- 
te code routines, as a continuous dump from memory. The header helds the load add- 
ags, so the program may be reloaded in the correct (i.e. original) place in RAM. Data 
\ stored sequentially in ASCII form, l.e. as if PRINTed to the tape, and, like disk 
equential files, the result can be read back, but not updated directly. This type of 
torage needs buffers in RAM, since there is no equivalent to the entire program in 
emory; instead, date is generated and stored in a buffer. When the buffer fills, it 

: written to tape and emptied. Conversely, when @ file of data is read from tape, the 
assette motor automatically runs from time to time, loading the next batch of data. 

t this point, without locking at the separate items stored on tape, lets consider tape 
ming, and the estimation of the storage capacity of tape in the CBM system. 





nocram rit: {-- LEADER --[BEADER|TONE] ~-PROGRAW (1)--|--PROGRAM_(2)~- f i 


DATA FILE: {= LEADER -- [HEADER paolo stro ia 2ND ued ae yes ; 
yl2 a) | (2 (1) | 42) 


Time (SZC3); 10 4 4 About .009 seconds per byte s2+ sec. gap 


fe can see from the diagram that 10000 program bytes are written or read in about 
96 seconds. 10000 bytes of data take more time, because of the ‘wastage’ caused by 
he inter-block gaps. The increase is something like 60%. (It may appear to be more, 
ecause the buffers need to be filled too), The amount of tape used is Increased in 
rroportion, Using approximute figures, 10000 program bytes require 3 1/3 minutes to 
tore or Joad; 10000 data bytes require about 3 minutes. 


CASSETTE TYPE: 1g _ C30 
Minutes per side: 





















C60 
















average B 
2 $ 8 16 


PER SIDE: 5K averuge 
ee ee PO vere. eV ie 8 
DATA STORAGE SPACE 1 fille Yt 9K 20K 30K 60K 


PER SIDE: 5 filen 13K 3K SK 11K 





There is little published emterial oa tapo aturage. Those wishing to know moro might 
ieasseuble their ROMw and oxamine ths result in gavociation with the avtna Ln Chapter 
4. A pair of articlos in Compute! (G Campbeli, tep./Uct.'HO and K Fatkner, Jan.’1} 
as, respectively, x mothod to load Applesoft programa (Apple floating-point BASIC) 
nto the CHM, and en Apple program to laad CAM tapen, Tha Latter ta a enll-docunented 
wucce listing, ‘28th error-recovery ‘potter than the PET’. Much of Lt convarts tokens 
ato the Apple equivalents, ancd porforna other functlons not very relevant ty th» CAX. 
Rabtlt' ig e 2-K package (avaliable on tape or ae a 2-H ROW (ADDD-ATFF) for fast 1oad/ 
ave of prograse onty. Itn rewrlta of the operating syatea denen't work with every 
‘ecorder, PCW (M Shelley, Jan. ‘'H1) hag o UAGIC 2 routine, with explanation, which is 
lestgned to help recover partly overwritten taped. (The explanation, Rowever, eye 
lothing of ite actual procedure). “‘apros” Le another feat tape eystem in rPRoM, 


aa 


ma 
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The table gives a guide to the storage capacity to be expected from typical 

types.* Thus, a C20 cassette will hold about 5 5K eronraiad: if hed ace cceorard 

consecutively. Each will take about 2 minutes ta record or read, because 10 minutes of 

playing-time is shared between 5 programs. 10K of data takes a jittle more than five 

minutes to record, and so on. Tapes can be played on ordinary revorders? and the 

Maria atte cheadai in Nee sayin diagrams on the previous page verified. There is 
rt tone separating the twa ves of the ecordi 

of which is recorded nice for besirlty, i ea aa a ai aia a as 


LOADing and SAVEing BASIC programs For detail on the workings of these commands 
see Chapter 5. Briefly, the syntax appears like this: ‘ 
LOAD “NAME"“,1 or LOAD “NAME",2  :REM SEARCH FOR PROGRAM CALLED ‘NAME’ ON 

CASSETTE#1 OR CASSETTE #2 
LOAD ee :REM LOADS FIRST PROGRAM ON CASSETTE #2 
LoaD 7 2 :REM LOADS FIRST PROGRAM ON CASSETTE #2 
LOAD "NAME" tREM LOADS ‘NAME’ FROM CASSETTE #1 


These examples show that the default is device {. The instruction 'PRESS PLAY ON 
TAPE #1' or '#2' always appears on the screen; further dispiay includes 'OK' when the 
key is sensed, and 'READY.' or ‘FILE NOT FOUND ERROR‘ or '?LOAD ERROR’, de- 
pending on the success of the search and load. When the program's header block has 
been found, the message "LOADING' or 'LOADING NAME‘ also appears on the screen. 
It the LOAD is carried out in program mode, most of these messages (l.e. unless there 
is an actual error) are suppressed, to kecp the screen relatively tidy. And if ‘Play' 
on the cassette is down before LOAD. no messages at all appear, unless there is some 


error. Loading from within a program causes the new program to begin execution once 


it has finished loading: the object is to enable programs to chain, keeping thei a 
lable values, With small {say 8K) machines, ints can be useful, both ie peincinc tte 
Processing capacity, and spreading the tape-reading time out. This may require care 
with the relative tengths of programs, and with strings (which must be stored in high 
RAM if they are to transfer properly}. Function definitions also aren't generally carr- 
led over between programs. (Chapters 2 and 5 explain in detail). 


SAVE 1s equally simple: 
SAVE “PHOG NAME", 2 :REM SAV£9 BASIC IN MEMORY ON TAPE #2 AS 
"PROG NANE' 


SAVE ‘HEM SAVES BASIC IN MEMORY ON #1 WITH NO NAME 


Security. To be on the safe side, SAVE important programs twice, either on the sa 
ig Or on a master tape. Note that SAVE always Meena the recording pronase. at a 
he point at which the tape is positioned; there is no searching provess as there fs 
with LOAD. As for LOAD, ?LOAD ERROR occurs if bit 4 of ST fs set. Sometimes 
Phils can occur in the absence of this message, and recommended practice is to print 
s to areek thet it is zero a8 it should be. A further refinement is to look at the re- 
ben ue the error-correcting processes of the operating system: PEEK(i92) for tupe #1, 
‘1 EK (193) for tape #2, should aigo be 0, although values up to and including 4 are 
80 acceptable, (For @ASIC 1, the peck locations are 630 and 631 respectively). 
eK LOADing in program mode does not reset 5T, so these tests can be incorporated 
@ start of a new progrum, if a wrong load would cause trouble. Or a machine-coda 
Teutlne to calevinte a hushtotal of the proyram bytes may be used, similar to that gupg- 
®euted for disk-based progrema in Chapter 6. However, these methods are normally 
used only when tapes are being tested of head alignment ja being checked. 


‘The figures ere calculated on the bests that each fife has 16 eeconds of ivatter; then 
Program storugn {BASIC or machine-code) takes a further .0008 x 2 seconds por byte, 
aince oach byte im recorded twice. Data atorayn takon plece in 191 byte chunks, cach 
ee written twice. The aumber of blecke required must be rounded up; wach takes about 
: saconds for the inter-block gap and 2 x {92 x .OU anconds to record ar road, Thre 
dag ia mhaut S$ maconds per 10t bytem (which fs ratner #elow). Far example, a 4000 
yee program ftin records in 16 + GH} = 106 asconds. 5090 data bytes neat 27 blocks 
taking 14 ¢ 27 x $$ = 583 waconds, s 


“ita Speakur la atteched to the sachine, as explained in Chapter 8, a pin un the user 
oe can be attached, lle CA2, and the program listened to walle loading. Ping 8 and 
‘ Tar tape #L read and Lape #2 read (ace manual) are tho unea. 

Seu e.g. D Ieaersun, "Detecting Loading Probleme...', in Computal Jan. ‘Al 


* ag — 
STP Tp ee REIS ey RTE EP Cal emia matioenet. aid eat salen 1 th demetaeaseniammninn tesheentie tellin. ter 10 leet te ememiinanaahiahnal 
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End-of-tape Marker When a tape Js being written 
PRINT) a secondary address of 2 - Strictly, of 
‘End-of-tape' marker to be written when the SAY 
This is quite a slmpte idea, but can cause some 
onto tape, exactly like any other buffer except 
is read back, a buffer of this sort is inter 
reading process will go no further. The marker need not actually coincide with the 

physical end of the (ape; @ 200-byte program can be saved with an end-of-tape mark, 
so if the tape is searched for some other program, reading will g9 no further than 


the marker, and the user will be spared the tedious Process of waiting for the rest of 
the cussette to read, Thus: 


&: Other peripherals 


(either by SAVE or by OPEN/ 

A AGn-zero even number ~ causes an 
E is finished, or the file CLOSEd. 
Puzzlement. An extra buffer is written 
for its very first vatue, When this tape 
preted as the end of the tape, and the 


SAVE "IMPORTANT PROGRAM", 1,2 
OVEN 7,4,2,"WAJOR FILE" 


respectively save HASIC to tepe i, with end-of-tape marker, aa IMPORTANT PRO- 
GRAM‘, or rather as the first 16 cheracters of this name; and open a file, for writing, 
to tape 1, called MAJOR FILE’ + aguin with end-of-tape. 


Writing and reading files: OPEN, PRINT #, INPUT#, GET#, and CLOSE These BASIC 


commands {with CMD) are all that is required for tape files. Although these files are 
really quite straightforward, they aren't all that easy to get used to; the next page 

i i « Which writes date and reads it back, printing 

i lor writing, without 
assigning it a name, and Print 256 values to tape. Lines 100-160 read them back, with 
GETH, so that each byte is separately read from tape; you will see that carriage ret- 
urn cheracters act as record separators. Lincs 200-260 read the same file with INPUTS, 


which accepts only a Tange of ASCII values, and also implicitly regards carriage ret- 
urns &8 separatora, 


OPEN and CLOSE typically look like this: 
OPENL iREM OPEN LOGICAL FILE 1 TO DEVICE 1 FOR READ 


OPEN 3,2,1, DATA" :REW OPEN FILE 3 TO TAPE 2 FOR WRITING; NAME IT DATA‘ 
OPEN 1,1 TREN SAME AS ‘OPEN 1° 


As these examples suggest, the four parameters (logical fle, device. secondary add- 
Tess, and name) have defaults, apart from the com 


faulting to read is of course intended to avoid accidental overwriti 

When a file is closed, its iast buffer ig written, with an 
This ia picked up on readback, setting ST to Its end-of- 
better to write some end-of-tepe marker, or to include a 
written, than to rely on ST, the treatment of which vari 

Tape files are sequential files, like disk files of t 
to the same rather painful restrictions. These ore made worse with tape by the fact 
that only one filc may be open at once, unless two crasette units are available. The 
ettempt to OPEN one file for read, and another for write, aithough legal, loavea the 
tape positioned as though only the second command had been issued. Tape data flies 
are therefore used only to hold data which was Input, or which is for printing, or 
which enn be updated entirely in RAM before rewriting to tape, unleas there la @ gec- 
ond cassette or disk unit. 


BASIC 1 (the oldest BASIC veraion) haa two bugs [n ite data file operating 
Bystem: gee section &.4 for corrections, , 


Storage of machine-code Programs and data via the monitor 
ood from the monitor ia illustreted by these exampicn: 


+5 “MACHINE CODER’, 01,9400 ULES. 
1G "WACHINE CODE" ,02 


thich save tho contents of inemory from 0400-0614 on tape 
ond Ut again, reapoctively. Note that .§ operates from the alart addresa untlt itm point: 
T equaln the end address: the lant byte does not get written to tape, C4n end-of -tupe 
wierker van be fureed by poking $032 211 with 2. (BASIC l: $02 240,. Ax we shall 

ce (Section 8.4} this process can bu carried out Crom HASIC, without untering the 
taniter, when the eppropriato locntions have boon found, Uefore Ula we tt wemlne the 
‘ay data Is held on tape In rather Kreator delail, which Joclides the structury of the 
enter block and the four typer of buffer which the PET/CBM nyntem haa, 


end-of-file zera byte. 
file value. It is probably 
count of the reeords being 
ex between ROMs. 

ype SEQ, and they are subject 


The syntax for save or 


fl as MACHINE CODE’, and 
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TAPE DEMONSTRATION PROGRAM: Showing how to write to septa ned the differences 
between the two methoda (’GET and “INPUT’) of reading it back. 


&: Other peripherals 


Seeeanaeeds 
SPEEA TELEEGESEIDELEREEGRDE EEE 
t nen @ SHORT BASIC TAPE DEMONSTRATION noe 
2 REM ORLERAPAHTAEE EEA EGEG ALES EARER ER ETES 
32 REM 
Sem arte) 
SPSOR CREEPER EGEEE ERE REEES 
; aM See0s# = =60WRITE TO TAPE Hatt 
7 REM HOPAPHRAEEAEE ERTL ELSE ER EEETES 
8 REM . 
9 REM 


: MBER = 1 
10 OPEN 1,1,1 ;REM OPEN THE FIRST TAPE RECORDER POR WRITING; PILE NUMBE 
2 


ERS 
5 Xe * CARS() fan TRE LOOP GENERATES ALL THE POSSIBLE SINGLE CHARACT 


iN F TN TEN. 
* 26 PRINT J::REM SHOW ON SCREEN THE ASCII VALUE OF THE CHARACTER BEING WRIT 
>” 


TURN 
30 PRINT#Z, X$ :REM PRINT A SINGLE CHARACTER - AND ALSO A CARRIAGE RE 
40 NEXT et 
60 CLOSE 1,1, a 
Hy "WRITING TO TAPE IS COMPLETE. ‘ 
a Pete PRINT “PLEASE STOP THE TAPES RECORDER AND REWIND THE TAPE; 
72 PRINT: PRINT'THEN PRESS ANY KEY TO CONTINUE. ohn Gvanbaatn 
73 GET X$: 18 XS = "" THEN 73 :REM WALT FOR ANY KE 


94 REt 


SePeeaserte 
FORERECAECORREAHTAULEPEATEEED SEE 

3 nee teene GET SINGLE CHARACTERS FROM Se ee 
97 REM ORREAHRESHORSERGER ELISE ESTEE TEESE 

98 REM 

99 REM 


ZADING; PIL® NUMBER = I 
i PEN THE FIRST TAPE RECORDER YOR R Ro 
see eee eng 320 CREST THE LARGER NUMBER OF “CRTS” RAS TD ALLOW FOR RECUR 

0 GET#L, X$ : REM GET A SINCLE CHARACTER PROM TAPE PO De 
ase X38 o "" THEN PRINT ASC(X$); :RFM KLUDCE, BECAUSE ASC(" 
ae IF X$= " THEN PRINT "NULL"; : REM FOR REASON GIVEN 
140 NEXT 


170 PetnT: PRINT “GETTING SINGLE CHARACTERS FROM TAPE IS COMPLET2. 


17L PRINT: PRINT "PLEASE STOP THE TAPE RECORDER AND REWIND THE TAPE; 
: “TIEN PRESS ANY KEY TO CO : 
is eerste ee = THEM 173 :REM WALT FOR ANY KEY TO BE PRESSED 


135 REM Seeaesaesgie 
HRPERPRT EEE ONTAEEEEE 

36 REM ¢#¢480> CMPUT FROM TAPE id Als 

197 REM OSORROEEAOEEEPEEAEET EE OTE EL TE 

198 REM 


FOR RRADING; FILE NUMBER.= 2 

t REM OPEN THE FIRST TAPE RECORDER 

2tg POE Ene 0 TO 260 CREM NOTE THAT THE SMALLER NUMBER APPLIES NOM | 

220 LNPUTEZ, X$ : REM THIS TIME, INPUT A SINGLE CHARACTER FROM TAPE 
“" THER PRINT ASC aa : . 

320 Ee Xs" THEN PRINT "NULL"? 1 REM POR REASON CLVEN BEFORE 


250 dali ; 

390 fer OOPERSESTEF 
27t REM ## END fF 
272 REM eons CENT 


i flio is 
! nc blacks Whon a program In saved to tape, or ¥ 
sepa gel a ast af cusaette operating syatem weritea a itty ae aed 
This ingle buffer of dats, contalning the prayram or file name. oe ae. 
oe fi es tu at the start, which the system identifies as the marke : bh 
ivan ee hen a prs rum (a loaded, ora file opened for read, the sail Wet, f 
cae ees f Lge a of the form which declure themselves as hencdera, es 
poner ds is aiid if it matches the required nama, loaded Into Tate aaa 
Heiiata unut GET# or [NCUT® ake foe data from subvwequent aici arch se i 
the flat headar on tape ite the cansette buffer for the atic aa alee Lig hare 
OPEN 1,2,0,"HEELO" londs ISELLO'R hendar ees connate 12s nto conwetto butter & 
fers are 192 liyles long, but o: di " : 
ee tte #i In SU27A - $OJd9 (614-825); Dulfor #2 im $033A - $0919 (926 - 1017) 


a 
* 


Py Callahan ie tne ae 
em, Fete Weer eT 
ear e S Ba a al eed aR Ae a aller ee ait Taina ian : 


™ 
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These buffers sre used only by tape, except in BASIC 4 disk handling with CBM 
disks. Consequently, if disks and tape ere both in use together, cassette #t only 
should be uscd; two cagsettes and BASIC 4 disks can be used provided the disks are 
not used while a file is open to cassette #2, Alternatively, the disks can be controlled 
by commands which avoid BASIC 4's special disk commands, coneat, dopen, delose,... 
Nate also that both buffers are usable to store machine-code, provided that no tape 
activity overwrites them. For example, a BASIC routine which pokes machine-code 
into either buffer is fine, and can be loaded from tape. But machine-code in buffer #1 
can't be saved to tape: the first thing that happens is that the buffer is replaced hy 
the header detnils of addresses and name, which will delete any code in the buffer, 
Buffer 2, when BASIC 4 disk coumands are used, is safe from $0381- $O03E8 (897-1000), 
The limits of the buffers are automatically set by ROM routines depending on the 
device number. See F667/F656/F695 in BASIC %/2/4. 


Program headers have this structure 


{a 1] 4 17| 4] 72 69] 78| 76 73 32| 32 | 32 3a| $ 


id, start end  pfogram name apaces 
$6401 $0431 a rk L L ° 


This header is for the program 10 PRIATHELLO” , which was foaded from a tape in 
cassette #1, So PEEKing 634 650 or so gives the decimal information Usted. (Note that 
BASIC 1 starte at $0400). The first byte is $02 = 1. 


Data headers have a marker byte of 4: 
a 
fatioe |2|sa{ a] 6s | es] se [65 32 | 32] 92 | 3a] 3 
4d, start end fils nane apaces 
$O27A $033A D A tT A 


This is the header for a file called ‘data’, which will load into cassette puffer #1. Note 
that the end address is recorded as $033A; in fact, addresses $027A - $0339 only are 
used by the file data as it is read from tape. 
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Data is stored in buffera of thie form: 


[2] 72 [oo ]z6]7e] 70 Jase [8 


CR, Zero 





The marker byte is 2. Data is followed by carriage return. (11 may also be separated 
by commas and colons; see INPUT in Chapter 5 for details}. The zero-byte is the 
end-of-file marker, wrilten when the file was CLOSEd. On detecting this, ST is set 
to 64, However, if ST is ignored, the zero byte is simply read past, and previous 
data (‘garbage') will be read. 


header, but with id=5: 


s[ se [sfoe [3 [sa] 2 [oe [o3]aa[ 


start end 


The End-of-tape header is a duplicate of the file's 
ot 1ap 








Thia example follows an unnamed data file stored in cassette buffer #2, 


Programs are slored in a single biock of data; ST=1 or ST=4, 'short block’ and 
‘long block’ crrors, happen if a program is read ag data. They-do not have a marker 
value; all the information needed to load them js held in the header. 

In addition 10 CHRS(0). which causes ST<64 10 be set, CHA§(10), Unefeed, ia 
treated as a special chnracter: in fact it isn't written (as date) ta a tape. There is a 
specinl routine to remove it, The absence of such a routine Ied to probiemsa with the 
disk unit's files, CHR$(29), cursor right, Also doesn't get throush. The demonstration 
program xhows these features. As far as INPUT# in concerned, thorgh not GET#, many 
chorneters sre anomilous: CHR $(13), CHR$(32), CHRS(I4), CHRS(44), and CHRS(58), 
which are Return, space, quote, comma, and colon, for exemple, give strange effectr. 
Lending spaces are deleted, for Instance. 

CMD enables programs to be stored as data; a date filo iz opened, CMD directs 
output to the file, then LIST eaves the progenm ne an ASCIL file, so that PRINT Is 
stored up $5 bylea, Sce ‘MERGE! (Chapter 5) for details and examples, 

Since OPEN 1 loade a program's header, Its load address and save address can 
be found with PEEK (635) + 256¢PEKK (636) and PERK(637) + {50°F EEK L648). The name 
can also be peeked out; no vnn any machine-code which may have been written into 


_ 
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the buffer as a security device. 


ROM routines and machine-code programming OPEN, CLOSE, LOAD, and SAVE canbe 
investigated by disassembiing the kerne! (the jump tsble almost at the end of ROM}. 
Each of these commands has 4 jump address here. Then, at some later point, after 
taking in the command's parunieters, & set of branches occurs: 


LDA $D4 , DEVICE NUMBER This, or something similar, ia the routine at 
BEQ uxxx;BAANCR JF KEYBOARD which JEEE devicea are separated from cass- 
CMP #03 ettes. The address after BCC is the start of 
BCC xxxx; TAPE ROUTINES the tape processing. After this, the two pease 
ible tape device numbers are distinguished in 
varlous ad hoe ways. for exemple by deerementing and branching if equal to zero, 
which finds device #1, The tape timing mechanism is complicated; it involvea both VIA 
timers, and clao resets the interrupt vector from a table; there are three interrup!s 
{apart from the usual keyboard servicing routine}, which deal with writing the header, 
writing data, and reading tape respectively. The keyboard processing ig cut eff, sono 
keypress get3 through to the keyboard buffer. But the stop key is tested by its own 
subroutine, so there is some control over the lape. A method like this is necessary to 
maintain accurate timing, since the keyboard processing routine doesn't take a const- 
ant dime. The instruction DEC $813 is used to disable the normal interrupt, prior to 
resetting the interrupt vector; it has the effect of setting bit 0 to 0, $E813 = 59411, 
go ihe game trick can be performed from BASIC: POKE §9421,PEEK (59411}-1 turns off 
the interrupt, and with it the keyboard and stop key; it also speeds processing 
slightly, The interrupt must be turned on again if the keyboard is to be reactivated. 
The table below lists some RAM locations, in the interface chips, which are rel- 
evant to tape, A few other locations (ROM and RAM) are included, where they are 
closely connected with cassctte operating: 


CASSETTE: ne CASSETTE #1 
ROM: 


BASIC 2 |BASIC 4 
Motor: On Bit 3 of 
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~ 
















CASSETTE _42 
BASIC 2[ BASIC 4 


Bit 3 of $E840 (59456) off 

] | Usual value $CF (207)} 

| Bit ¥ of SE840 (59456) on 

{Usual value SDF (223) 
FA 

















$E813 (59411) off 

[Usual value $35 (53)) | 
Bit J of $813 (594811) on 
{Usual value $3D (61)) 
g07 (519))  $F9 (249) 






















off 














SYS 64763] SYS 64635 | SYS 64704 
Bil 4 of $EB10 (59408) off 














Key Sense pressed * Bit 5 of $EB10 (59408) aff 


not pressed 















Bit 4 of $E819 (59408) on Bil 5 of $E810 (59408) on 








$272 (626) SBC (188) 
“T3035 - $03F9 (826 - 1017) 
Bit 9 of SE94D (59469) 

Fe et ck ae hel 


a 


$271 (625)! $BB (187) 
FO27A - $0339 (634 - 825) 
Bit @ of $E811 (59409) 
“pit 3 of SEQ40 (59458) 
















Tape write interface 













game 


“Ir non-zero, the contents of this jocation signal that a cassette key ia preased 
“Reverse, Faet Forward, or Play 


The tape motor{a} can be turned on and off from within RASIC with tho help of data 
from: this chart. A complicating factor Ig the IRQ service routine (E685/FG2E/E455), 
which under narmal circumstances turns off elther or both motors if it finds them on. 
(The geeucnee LDA EB10/ ABL/ ASL/ ASL tests the onssetle sense line for both cagsa~ 
etlen: if the curry fisg is set, a button js not presred on cassette #2, and if the min- 
us Mag jx act, a button Ix not pressed on cansette tl, in eithor euso the motor ts 
lurned off, provided the cussette status flag (antcrisked in chart) is zero). To avoid 
fie motor bring turaed off by the usual interrupt processing, poke a Non-z0ro value 
into the status Mag location for the cassrtte, 
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OPEN, CLOSE, LOAD, and SAVE can of course all be performed from machine-code, 
To sce how the inbuilt routines might be used, let's consider some published examples 
of uxiorthodex use of the cassettes: 


(i) A program can be loaded into addresses different from those on the header, 
by first loading the header alone, then changing its pointers and loading the remaind- 
er of the program. [t could, for example, be watched loading into the screen; or a 
machine-code routine, saved on a machine with a lot of memery, might be loaded into 
a amuiler machine in this way. 

(i} ‘Append’ of tape programs or subroutines can be achieved by loading two 
Ptograms so that the second starts where the first ends. 

Gil) A program can be saved along with data in its header. Normally, this can't 
be donc, since SAVE clears the buffer. filling it with spaces, before pulting the start 
and end addresses and program nanie in. [f a program is saved with machine-code in 
its header, this acts as an anti-copying device up to a point, since SAVE in the usual 
way will erase this bulfer, so the capied program won't run if the buffer's routine is 
essential to it. 

(iv) Another anti-copying device is to change the header pointers so a program 
loadsa into the keyboard buffer. It can thus be made to RUN immediately on LOADing. 
Provided the stop key is disabled, the program is made relatively difficult to enter. 

(v} Some programs for BASIC 1 ware made ‘uncopyabie’ by setting the header 
pointers to start at an address below the start of BASIC, causing SAVE not te work. 
icrochess' used such a principle; it also included its own save routine, so that an 
appropriate SYS call copied the program. : 


The table which foitlowg should provide a useful map for those readers who wish ta ex- 
plore tape ROM. Some significant ROM routines and RAM locations concerned with load- 
ing and saving programs [rom/ to tepe are listed. Roughly speaking, the lower-levet 
aubroutines are further toward the end of ROM, so the trickiest programs must use 
routines with higher ROM addresses, 


FUNCTION/ LOCATION 


Tape LOAD (assumes parameters are set) F3A5 
Tape SAVE (assumes parameters are set) — F6Fé 
Save (ive. write) header (LDA #1) or e-o-t (LDA HS SAE 


Save program or own header etc.* i) 


BASIC 1 BASIC 2 BASIC 4 











Load (i.e. read) next header 
Load named header 

Load rest of program 

Load any data* 


Device number (1 or 2, stored es $01 or $02) 
Length of name (0 meuns no name assigned ) 
Start address of name, if there is one 

Start address for load/ save 

End addrean -f for load/save : 

Load/ verify flag (0 =load, | = verify} 
Secondary address (i,t, or 2} 

Delay before writing 





FSAG 1 FBES 





*atart and end addresesa, and other parasaters, seed to bn oot. 


Examples. (1) Loading machine-code or BASIC into screen RAM: The eusicat de- 
monatration Ia to load the header, charge iis pointers, and load 1 or 2 K of the pro- 
gram. OPEN 10 reads the first header on tape #1. Locationa §027A onwards (i.e. 
624 onwards - try FOR J = 644 70 884: PRINT PEEX(I);, NEXT for [.d. and addresses 
and ASCH] values of the name) told Lhe header, so we poke the atart siifress with 
$4000 und the ond address with $4400 or $¥80G. POKE 635.0; POKE 636,128: PORE 4370: 
POKE 630,132 or 138 works for any ROM. Then calling F3C3/F3H9/PIFR completes tne 
fond, ufter taking these addresses form the buffer. So (depending on the ROM) 

SBYB $2409/ 82943/ 62458 completes the lend into sereen KAM, 

(il) Savlag machine-code from HASIC. KAM enn be sayed to tape as a nanied 
program fite without entering the monitor. All thot'a needed Ja to puke awl the rolevunt 
parumeters inte place, and call a routine whieh writes lo tape. Thia is not entirely 
airaightforward, because ihe X-reyistur nueds to be landed with gero before SAVE in 
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called, and this can only be done in machine-code. If we save this machine code at the 
start of BASIC, we have a routine like this: 


O REM "S$ Iv" SYB TOIL CALLS: LDX #1 DEX JMP $FEF6 or $F703 or $F742 
1 REM BYTES IN 21031-1036 ARE 162,1,202,76, AND THE 2 JUMP BYTES (LOW-HIGH) 
20000 REM © SUBROUTINE TO SAVE MEMORY IMAGE TO TAPE OR OISK FROM BASIC * 
10010 REM * LIMITS ARE $0400-$8000, AS CASSETTE BUFFERS ARE USED, AND * 


10020 REM * MEMORY ABOVE $5000 ISN'T SAVED ON TAPE. * 
10050 REM * INPUTS. B=BOTTOM OF MEMORY TO BE SAVED, TeTOP+2; N§=NAME; * 
10040 REM * 


10050 PORE 251,H AND 255: POKE 252,8/256: REM BOTTOM ADDRESS INTO ($FB) 

10060 POKE 201,T AND 255: POKE 202,T/256:; REM TOP ADDRESS INTO (C9) 

10070 POR J = 0 TO LEN{(N$)-1: POKE 826+3, ASC(MIDS(N$,J+1)): NEXT: REK POKE NAME 
INTO CASSETTE BUFFER #2 

10080 PORE 212,1: POKE 209, LEN(N$): REM DEVICE IN D4; NAME'S LENGTH IN DI 

10080 POKE 216,58: POKE 219,32: REM 033A = (DA) = START OF NAWE 

10100 S¥5 1031: RETUAN : REM CALL SAVE ROUTINE 


Note than line 9 has been used to store machine-code. Everything after REM is ignored 
so this is perfectly acceptable. However, there must be no zero in the line, or it will 
be treated aa an end-of-line marker and generate a spurious line if the program is 
edited; hence the use of LDX #1/ DEX in place of LDX #0. The bytes remain intact 
unless line 0 is edited, in which case some may be changed - peek them to check. 
Quite tong machine-code routines can be stored like this. Note that BASIC i has a 
different set of zero-page addresses, which can be faund in the table on the previous 
page. 


9.3 Miscellaneous: fast forward winding, directories of tapes, BASIC 1 bugs, security 


Timing fast-forward tape movement CHM cassettes have no Cast-seek facilities ot the 
sort which are sometimes met with, for example in the ‘stringy floppy’ with loops of 
tape, or certain af Sharp's machines, which store a marker on track 2 of the tape, to 
give advance warning of the presence of a header, This perhaps makes no great diff- 
erence; tape is inevitably clumsy compared with disk. Nevertheless it is possible to 
say a few useful things about fast-forwarding tape. * 

tn fast-forward mode, we can assume that the drive motor 1s rotating at a fixed 
Speed, so - with apologies to those who don't know calculus - after time t seconds, 
the distance (ds) the tape moves in interval dt ia proportional to the circumference of 
tape on the tuke-up spool x dt. This circumference = 2*pi*(radius of spool + k*t), 
where k is a constant related to the speed of the motor and the tape thickness. 
So 8 = k)jk2 + k3tt dt = kyt + kot?. In other words, we can expect. or at least 
hope, that a simple quadrutic expression relates fast-forward time to distance along the 
tape? The diagram Wustrates the situution. In fuet, this model does spprouch reality 
with sufficient precision to be usefut. Note that the tape la predicted to advance faster 
towards the end, which of course it does. 


4 Faat-forward 
Distance 


along tape rual 








The point of this type of relationship ls this: suppose we have a program on tape 
which is (gay) 5 minutes’ playing-time from tho start. Can we estimate the fast-forward 
equivalent time? If we heve a graph like the one sketched sbove, we can siaply read 
off an estinnted time; in view of Uhe lalltuds allowed by leaders, this is usually good 
sheuyh to flid the program in a reasonably cost-eflective wiy. 


“*Articlaa (ompiricul rathee than theoretical) jaciude ‘Thomas, IPUG Jan ‘80 and Bopt. 


‘SU and W McGrackun, CPUCM #7, ‘Micro’ has publiahed articles on this topic. 
"Aoadara who have follows me so far will be able tu chock that: 

ds e circyuaferonce * reve.par soc. © dt, ao that 

aevue*pi*tradiue uf apool + rave.per anc. *thicknosea*t) ¢ rava.par voc. © de 
Bo Past-forward distance In Tp wuca, © 2*pi*rpe*tradiuatt + rpeetnet"s2), 
Diatance in normal operation = 1 7/8 * t, laches. So tha ratio of faat-farwacd to 
Oormal time required ta cover mage figzed distance of tape in taplicit in 

LT tty Beplervat ret, © 2eplerpaternet! 72. The cunstante can be gueseed of 
@rssured to provide # gumdratic equation, | typleally, ta the fteet tere, ter. ON * ty. 


“ 
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[here are two ways in which this information can be applied. We can design a tape 
system so that a number of equal spaces are allocated on tape; in this way, we can 
‘ast-forward to any program, either to write or read it, fairly easily, Alternatively, we 
san write 4 directory program which reads any tape, printing the times taken to find 
zich program, and perhaps predicting the corresponding fust-forward time. (The pro- 
grams of McCracken aud Thomas respectively illustrate these approaches). For a 
asrecise job, it's necessary to write test data to tape, then read it back after a timed 
‘ust-forward. A program to do this is probably of too limited interest to be included 
yere. How can fast-forward timing be measured? We can turn off the motor after a 
oredetermined time like this: ry 


10 INPUT "NUMBER OF SECONDS FAST FORWARD" ;S 

SO PRINT “PRESS FAST FOAWARD KEY" 

30 IF PEEK(59411) <> 53 GOTO 30 ;:AEM AWAIT EEYPRESS 

40 T « 60°S + TI 

$0 IF T1<T COTO 5D REM TIME LOOP FOR 6049 JIFFIES 
60 POKE 249,1: POKE 59412,61 REM STOP MOTOR (USES STATUS FLAG) 


ind in this way we can fast-forward to any point on tape, 


Tape directories It is easy. and useful, to write a program to list the contents of a 
‘ape. It is true, however, that such a program will be slow, and isn’t really a substit- 
ite for notetaking on the contents of tapes. The program below repeatedly loads head- 
ars, reporting the start/end addresses found, printing the name of the file, and rep- 
wting the time taken to read the tupe at normal speed. 


10 TO=TI: OPEN 1: Tl=TI: CLOSE 1 : REM READS HEADER; T2-TY 13 TIME TAKEN 

20 PRINT "NAHE:";: 

30 FOR J = 633 TO 654: PRINT CHR$({PEZK(J)};: NEXT ; PRINT: REM 16 CHARACTERS 
40 PRINT "START ADDPESS"; PEEK(635) + 256*PEEK(616) 

50 PRINT “ END ADDRESS"; PEEK({637) + 256*PEEK(638) 

60 T= T + (TL-TH)/69 

70 PRINT "NORMAL SEARCH TIMES"; T; "SECONDS" 

90 GOTO 10 :REM CAN INCLUDE END-OF-TAPE TEST, PEEK(834)=5 


[his simple program cun be enlarged to report whether a file holds a program or data, 
‘or which PEEK(634) is lL and 2 respectively, Hex addresses, likely BASIC programs, 
astlmated fast-forward times, and the contents of headera which have other than 
spaces after the program name, are examples of the sort of thing which may be of use. 


3ugs in BASIC 1's tape handling There are two serious bugs in the duta file operat- 
on of BASIC 1, mot the program loading and saving, which can be corrected by soft~ 
ware kludges. (i) A write file opened from cold doesn't set the pointers to cassette 
suffer #1 or #2 as it should; poke them into (F3) with POX 243,122: POKE 244,2 
($027A for cassette #1) or POKE 243,58: POKE 244,3 ($033A for caasette #2). 

(HW) The interblock gap doesn't allow for motor start-up: the kludge 
‘or this 1s to start thé motor before the buffer is full, a.g. 


40 PRINT#L,Z$:REM WRITES DATA TO TAPE FILE #1 GN CASSETTE 1 
$0 IF PEEX(624)21980 THEN POKE 59411,61 :REM MOTOR ON 


fo value of the parameter in tine 50 dependa on the length of the strings being 
yritten to tape, end the frequency with which they are written. The maximum value in 
525 le 192; allow enough time for the motor to run about t/Ird second. 


Aiscellannous (i) Tha ‘<" key. There Ja a programming error in BASICs | and 2 which 
nokea this key appear to relate to enanette #l. (See locations SHIAB ff. tn BASIC 2, 
‘or example). Beenuse of this, if a key lx sensed from cnasette WL, '<' ropenta if tt is 
wid down Wf for example the tape holds a recording. Somatines '<" appeura to 

rocome inactlye; poking H9il (59409) so bit 7 is iow may help, a.g. PUKE 69409, PEEK 


(69409) AND 127, 

(il) s¥8_624A5/ 62493/ 62556 print the last-londed or tast road name to 
he screen, doth for cassette #{ and cassette #2. ‘ 

(44) Security. Tapes are luas copyproofadie than disks, becnunea ardin- 
ry audio copying can be used (and is, Cor commercial duplication of proyrams an 


ape). An interesting routing (‘Auto-Run-Save') for BASIC t only by W Kolbe 
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in Micro’ (Sept. '80) enables a BASIC program to be saved with a modified header so 
that it always runs immediately on being loaded, This, combined with disabling of the 
Stop key, provides considerable security against LISTing and amending of BASIC. The 
program (‘Auto Run Saver’) offers a further possibility of modifying the interrupt to 
test for direct mode at every interrupt, and calling the reset routine if direct mode is 
detected. This makes automatic running very secure against LISTing. (Something iike: 
LDA $78/ CMP #02/ BYQ RESET/ JMP [RQ inserted before the normal interrupt detects imm- 
ediate mode; in BASIC 1 the equivalent is LDA $CA/BEQ RESET/JMP IRQ). Unfortunate- 
ly, while this process is relatively easy for BASIC 1, BASICs 2 and 4 have been re- 
organised in a way which makes auto running difficult te achieve. (It can be done 
with disks~- see Chapter 6}, This diagram shows why: 


some HEADER (192 BYTES}-~--- KEYBO. BUFFER PROG, ~---MAIN PROGRAM-~~--~- 
BASIC ar MACHINE-CODE 
- SS(RE 
Pee este ane fuacaree-cooe) [| frsesecermn with e.g. SYS 1037 
634 639 655 


The program is saved in three parts, not the usual two with a header and program. 
The diagram is intended to be read from left to right; this is the order in which the 
three components are saved to tape and read back, The header has a start and end 
address pointing to $020D to about $0218; these 12 bytes include the keyboard buffer 
{$020F - $0218) and the location holding the number of characters in the buffer. When 
the header loads (into cassette #1 only), the short following program is loaded and 
direct mode is entered; but since the program deliberately fills the keyboard buffer, 
the operating system inputs the buffers contents, which are SYS 656 [Return]. The 


header has machine-code saved with it; this is called by the SYS command, and has 


two functions: (i) to put Run [Return] in the keyboard buffer, (il) to load the next 
fi-e. ordinary BASIC) program using the header already in cassette buffer #1. So the 
program is loaded and immediately RUN. 

BASICs 2 and 4 have the keyboard buffer in the same place as BASIC 1, but the 
location containing its contents has been moved ta the zero-page. This means that the 
intermediate pseudo-program must lond inte a region which crosses the stack. Since 
the tape loading routine uses the stack, this is difficult or perhaps impossible to arr- 
ange. The only alternative seems te be to load a one-byte 'program' into the IRQ vec- 
tor, ($90), in the zero-page, to temporarily deflect the interrupt into machine-code in 
cassette-buffer #1. This seems impossible with BASIC 2, because the interrupt points 
to the wrong part of memory, but it should be possible with BASIC 4. 

To save a header and program with machine-code included in buffer #1 and wlth 
any toad address and end address, use thie routine, which can be called from BASIC 
or machine-code: 

This routine writes o header, including 
program name and machine-code, using 
details assumed to have becn assembled 
directly in cassette buffer #1; other 
locations of course are possible. I[t 
also writes the program which the 
header will load; a second program, to 
be loaded by the header's machine 
code, can be written by entering 4 
second set of start/end addressca and 
writing the bytes without a fender. 


START LDA #01 
STA $04 ;DEVICR #1 = TAPE #1 
LDA #7F 
STA $DA =; POINTER TO START OF 
LDA #02 ;NAME, ASSUMED PRESENT 
STA $DB IN BUFFER #1 
LDA #AA ; LENGTH OF ‘NAME’, I.E. 
BTA $01; INCLUDING M/CODR 
LDA STLO 
BTA $7B ;LOAD ADDRESS TO BE 
LDA STHI ; STONED IN HEADER 
STA §FC 
LDA ENDLO 
STA $C@ {END ADURESS TO BE 
LDA ENOUT; STORED IN HEADER 
BTA SCA 
J8R $YO54.aeT TAPE #1 BUFFER [BASIC 4:¢7095) 
JRR $¥B47 AWAIT PLAY & RECORD [BASIC 4; 9FHAC) 
LDA #01; HEADER TYPE «= 1 
JER SYSDA WRITE HEADER [BASIC 4: $7619} 


LDPAO BTOME POIMTEA TO START OF PROGRAM 
OR PSRUDO-PHODRAM IN ($F9} 
ATORE POINTER TO END OF PROURAM 
OR PBEUDG-PROGRAM IM COUN} 
SMP SF71B, BATE WITHOUT HRADAR [(HABIC 4:9F76A) 


4 
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rinters In generat Printers serve several purposes: they enadle permanent records 

> be kept on paper, for example of program Listings’, as they are invariably called. 
hey enable data to be output in 4 more-or-less readable form, as ‘printout’, This may 
clude both finished output and audit trails. Finally, they can produce documents with 
sutures which mimic typed or printed output, for use in word processing, letter-writ- 
ig, and so on. In principle, they are simple: often they are receive-only devices, 
hich convert a limited range of bytes into characters. In practice there are several 
omptications making this aim difficult to achieve. Some printers, usually the more 
xpensive daisy-wheel type, are available with 'KSR' (keyboard send and receive) 
satures, enabling messages typed at the printer to be received by the computer, but 
‘e need not consider this aspect in detail, since it is unlikely to be useful except for 
onfigurations of several remote computers. Let's first lock at the current methods 

y which the actual impression is made on paper, before considering the questions of 
iterfacing and of firmware. 

In approximate order of expense, these sre the printer types now available: 

(i) Teletypes. These provide a paper terminal which can both send and receive 
ata to a Computer. They were widely used in computer installations, but have been 
argely superseded by VDUs. They are rather large. heavy, and noisy, and have 
pper-case text only; however, second-hand models can be got very cheaply. The 
iterface is RS232. 

Gi) Thermel and spark printers. Printers of these types require specially pre- 
ared paper, sensitive to heat in one case, and conductive in the other. Characters 
re made up of dots on the dot matrix principle. Thermal printers have a head con- 
aining elements which rapidly vary in temperature, causing dots to be plotted as the 
‘ead moves scross its puper. Spark printers use aluminised paper; a series of small 
igh-voltage bursts burns dark marks on the paper. Printers like this are silent, but 
he paper is expensive, and usually available in narrow rotls only. 

{iii) Modified electric typewriters. Reconditioned golfvall typewriters with an 
nterface to accept computer data have had some popularity before prices of dot-matrix 
winters dropped to competitive levels. They produce good-quality text, out the speed 
s limited by mechanical components driving the golfball. 

(iv) Dot-matrix printers, These are by fur the most widely-used printers with 
sicrocomputers. The print-head, made by a specinlist manufacturer, has typically 7-9 
tires arranged vertically, which are driven into contact with the ribbon and paper by 
wlenoids, each wire having its own solenoid. The 4022 for example has 8 wires; ag the 
leed scans the paper, any of the 256 combinations of wires printing or not printing 
‘an be triggered, and churucters are built from these fundamental dot patterns. Each 
1022 character is 6 dota wide. so six separate sets of impacts make & charneter, unless 
iome of the ‘impacts’ are of a blank column of dots. So, for example, a printer working 
it the rate of 100 characters per second, with an 8 by 6 character structure, makes 
j00 sets of impacts per second maximum. Printing at this maximum rete may cause 
sroblems of overheating; 4022 users are warned in the manual not to print much text 
n reverse charocters. 

(v) Daisywheel printers. A 'daisywheel’ has 100 or so spokes (or 'petats’!) 
ranged rady tty around a thicker hub, ench spoke terminaling in a raised, reversed 
tharacter. The wheels ara mnde of tight motal or plastic, designed with low rotational 
nertia so that they can be spun fast. Fortunately they are lergely stundarniged, 80 
hat (for example) Qume and Dinbto wheels mun on each others’ machines. Some wheels 
‘e.g. Ricoh) have upper and Sower caso on the wame spoke. Spoede of 50 or 60 ch.p.8 
ire quite common. The print quality ls good. As ia the case with golfballa, the common 
etters (¢,t.9,4,0,0,8) are clustered near euch ather, to cut down on time spent mov- 
ng the correct letter Into pinee, ‘Spinwriter’ is simUor, but usea a ‘thimble’. 





Features of printers A few words on stationery, ribbons, switch-aclectable printer 
‘aturus, and maintenance ara necoswry here. 

(1) Paper drive mechnnisms and statlonery. Computer printars normally ust 
rontinuows fan-fold atalionery driven by saprockoted rollers. ‘Plafeed' or ‘sprocket 
feud’ usually implies that the roller haa sprockels of a fixed separation "teuctor food! 
mplies voriable width, the ‘tractors! being nhie to slide niong the roller, and, in some 
Joxlgna, aproending the load over several perforations with a cnterpillar -track arrange” 
nent. 'Plnehfeed' permits some printers fo uae unperforaled stationery, 2. telex 
papar. Slagle sheotsa can bo fed, one at a lane, Uning ‘cut hast fuodera', theau ote 
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optional extras (usually for daisywheel printers) and are expensive. Computer station- 
ery can of course be obtained in multi-thickness form; printers vary in thelr capacity 
to handle copies. 

Gi) Ribbons, Many printers have cartridge ribbons; the cloth type is arranged 
as an endless loop, held within the cartridge either loosa, packed in a random pattern 
go the direction is constant. Also the typewriter-style spoals which reverse direction 
are sometimes met with; these are cheaper than cartridges, but there is a risk of dam- 
age with some types of ribbon, for example through clogging the print head (with the 
wrong type of ink) or bending the wires (with eyelets in the ribbon). Carbon or film 
ribbons are used for high quality impressions with daisywheel and golfball printers. 
Multi-strike ribbons are more economical and give a slightly inferior appearance. Such 
ribbons offer once-only use, and it may be important to ascertain how much work 4 
single ribbon can produce. since otherwise a program run may require more attention 
than ought to be necessary, at a greater cost. 

(iii) Features. External switches on printers - apart from on/off! - may include 
paper control (paper feed, set top-of-form, move to top-of-form) and/or automatic 
linefeed on/off, at the simptcr levels, up to a full range of facilities, controlling baud 
rate, parity, horizontal and vertical ypacing, margins, tabs, ete. Internal switches, 
accessible only by removing the lid, may be used to set characteristics like the baud 
rate, the type of interface, and (e.g. with Centronics printers) the type font suited 
to national needs, permitting currency symbols, diacritical marks, and special charac- 
ters (Dutch 4}, German §) to be printed. Many printers have some form of self-check 
or ‘internal diagnostic’ routine; Commodore's smaller printers for example have two 
channels available on reset, so switching on with the paper feed button pressed causes 
a jump to be made to a subroutine which repeatedly prints out the character-set, 

The speed of a printer is usually quoted in characters per second or lines per 
minute. Neither measure is completely satisfactory. A 50 ch.p.s. daisywheel printer 
may produce a fairly sparsely-filled document more rapidly than 4 matrix printer rated 
at twice the speed, by skipping blank spaces instead of covering them at the same 
apeed as the text. A bidirectional matrix printer is likely to be faster than a similarly 
rated unidirectional printer, because it need not waste time returning to the leftmost 
margin after every line, A printer with a large buffer may take less computer time to 
print, since the buffer (RAM held within the printer) may be able to accept lurger 
batches of data for printing before spending time handshaking, waiting to take in the 
next batch. Some ‘intelligent’ printers move to the next line when they detect that the 
rest of a line is blank; ‘Lines per minute' is a useful measure only when this docsn't : 
panne and even then there may be variability if the lines' total length can be con- 
trolled. 

Meintenance ig generaily a dealer function; some machines may have to be deliv- 
ered by the user, particularly if they are cheap, even if there is a maintenance 
contract. [t is worthwhile estimating the probable amount of use of a machine; if (aay) 
an average page has 60 lines of 50 charactery, a box of 1000 fanfelded shcets takes 
3 miflion charactera. 

Printer features which are relevant to operating convenience inciude noine, port- 
abllity, ease of paper loading, and, with nome models, the choice between A free- 
standing machine or the desk-top equivaient. 


8.5 Commodore and CBM-pluy-compatible printers 


2000, 3000 and 4006 series Theae printers are Commodore's siandard low-cost range. 
The 202% and 2023 are, or were, 80 column printers, the first having ‘tractor fend’, 
{.e. sprocket drives of adjustable separation andthe second, cheaper, model pinch feed, 
These were renamed the 3022 und 3023 to enineide with the 3000 seclun CIM computers, 
The 4022, with tenotar feed, superseded these at about the start of 1941. There Is no 
$022. [t differs from ita predecessors, and in fact ia closuly related to the Epon 
MM--70. The firmware in these printers hag not been completely successful. Two sets 
of ROMa (set 3am set 4) have been Ismed, and others have been tested Gut nat 
fadued. Apart from miner tugs, the principal error ia lay the handling of lower-case 
lettering, which hua te be dong ina way not compatible with sutpat to the sereen or 
to other printers. Future ROM twaues will have to be duaigned on the buds of the 
Sfflewlt deelsie of making the printers caxy ta uKe, but incampatibta with todating 
CUM printer software, or to retain the previous weaknessen. 
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The 8622 dot-matrix printer This printer is wired as IEEE device #4. It is controlled 
by a 6502. A red LED gives evidence that a channel ig open to receive data. The dot 
matrix ia 8 by 6; most characters are printed within 4 7 by 6 rectangle, with descend- 
ers and the lowest line of reversed characters occupying the bottom rew. The printer 
is controlled in two ways: firstly, a range of secondary addresses enables semi-perm- 
anent aspects of a printout (lines per page, spacing between lines ete.) to be get; and 
characters similar to the screen-editing VDU characters enable the second set of more 
temporary features to be controlled. These include reversed characters and multiple- 
length, ‘enhanced’, characters, The 4022 has 1L secondary addresses: earlier modeis 
had 7. We shall first look at these secondary addresses. 1 have assumed that a chann- 
et to the printer hag been opened with OPEN 4,4. Other channels, which assign a file 
Number to a secondary address. also need to be opened, and usually it is easiest to 
number the file equal to the secondary address, for example OPEN 6,4,6. A few points 
are worth noting: PRINT# has to be used as a rule, because CuD followed by PRINT 
sometimes fails to work (e.g. after GosuB). Some parameters have to be entered as 
CHRS(). although this is not mentioned in the manual. If a command seems not to be 
working, try the combinations of (say) "60", CHRS(60}, and 60 until you find the 
correct formulation. And the special features of output formatting and of user-defin- 
Itlon of s character only apply to a single format string and a single character at one 
time. So a table, in which each line resembles the previous line's layout, Is straight- 
forward to print; whereas interleaved lines of different format require that the format 
string be redefined within the printer. Finally. beware of plugging the printer into 
the PET/CSM with its plug upside-down, which may be possible if the polarising pins 
in the plug work loose; this will damage the computer, 


4022 
Secondary addres 


tt] Print ‘as received' | This is the default option (no secondary address. 
Tab, Clear, etc. don't work; hangs on back- 
space, CHRS$(20). 

1 Print in format Prints according to the format last printed to 

secondary address #2. Overflow (or other error 

resets secondary address to 0, fills the field 
with warning asterisks, and printa out the typ¢ 

of error if this is enabled by sec. address #4. 

A single format can be defined at one time in 

COBUL-like form, e.g. $5$3$9.99 causes 12.345 

printed to secondary address 1 to appear as:- 

+ $12.34 

3 Set Jines per page {| This seta the number of tinca which are printed 
before six dlank lines automatically print (to 
move past the perforstions}. CHR9(147) turns on 
paging; CHA$(19) turng it off. 

§ Enable diagnostics | OPEN40,4,4: PRINT#40:CLOSZ40 causes diagnostic 
messages to appear on errors, There are six 
messages, consisting of a alngie letter pretixed 
by '*PE:'.) (Printer Error’ presumably), 

3 Define chseracter Define own CHR$(254). One only at a@ time. 
Can't be changed during a linu; this gives a 
‘Terminator error’. Cun print several on one tin 
using CHR9(141) au Return without Inefeed. 

‘ Set vertical spacing | OPEN 4,4,6: PRINT#HS,CHR&(N); CLOSE 6 Bete the 
line sacparation ty 144/N inches. So CHRS(1H} 
ptinia & linesflnch, keeping the characters 
their uaunk height, ao there ls no separation, 





2 Define format 


? pper case OPEN 7,4,7: PRINT#7: CLOSE 7 

8 ower case (ip part) OPEN 84,8: PRINT#B: CLOUK § 

9 Disable diagnostics | OPEN 9,4,9: PRINT#9;: CLOSE & 

10 Reset Roxet all the semi-permonent features sat via th 


secondary address to the values obtalning on 
switch-on, with OPEN 10,4, 19; PRINT#10;CLOBE 19, 
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The most significant aspect of printing in formats is that numbers are easier to deat 
with than would otherwise be the case, 23 and 1234.567 can be converted instantly to 
23.00 and 1234.56 with these printers. Unfortunately the formatting process deals only 
in whole tines, so it often happens that text is mixed with numerals. and text is often 
easy to align without the need for a format definition. in other words, when printing 
a mixed output of text and numerals, the textual pert may well be more tiresome to 
arrange in fortmatted form than it would have been to print out directly. The full 
details of formatting, with examples, would take foo much space here, but the short 
example which follows illustrates how a literal, a string, and a numeral can atl be 
simultaneously formatted. 

The object is to print a single line, given a name N$ and a sum of money D (in 
dollars - the only currency synibol available when formatting), When a set of lines are 
printed, they are to appear like this: 


PAY ERROL T, ZINZINHEIMER $45.67 
PAY J. DIBBINS $7.50 


that is, the word 'PAY' followed by the left-justified name N$ and finally 0, formatted 
to 2 decimal places and preceded by '$'. The following program rounds D to the nearest 
half-cent as well: 


100 OPEN 1,4,1: OPEN 2,4,2 

110 PRINT#Z, "(RVSJP(BVS)JALHYS]Y AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA $S$$S$. 99" 
120 INPUT N$,D: REM NAME AND AMOUNT 

130 PRINT#1,N$ CHR$(29) D+.0045 

140 GOTO 120 


Line 120 causes a format to be stored in the printer's RAM. Note that a reverse char~ 
acter signals that the next character (only) is ta be treated as a literal: hence line 
130 prints ‘PAY’ immediately, followed by N$ left-justified into the alphabetic field, The 
cursor-right or 'skip’, CHR%$(29), Forces an end to the field, so the numerul with the 
leading ‘$' and numerals after the decimal point prints next. The maximum value is 
9999.99 in the example; if secondary address #4 is active, D larger than this will gen- 
erate a brief and modest error-message, which the programmer can pretend has some 
esoteric function. Even if D is zero, the decimal point appears: $.00 and this keeps 
the appearance tidy. There is no easy way to retain a leading zero for values less than 
1; .55 is easier to print than 0.55, although many peopte prefer this latter form. 


Error messages, The 4022 has 6 diagnostic error measages, which are printed if 
secondary address #4 has been enabled. These are: 

*PE:C* ... Secondary addrega exceeds 10. 

*PE:E* .., Exponent error; number in scientific format requires E*xx. 

*pE:F* .., Format sent to sccondary address #2 waa invalid. 

*PE:1.* .., Linas per page, sent to secondary address #3, were out of range. 

*“PE:M* ,.. Mismatch - alphabetic data sent to secondary address #inumeric field. 

*PE:T* .., Secondary address changed before Return or Linefeed send. 


4022 printer contro! characters. These characters are printed to the channel 
with secondary address Zero, either in quotes or in the form CHRS(x). They are exact- 
ly analogous to acreen editing characters, such 4s cursor right or Clear, which may be 
‘printed’ to the sereen. Jn fact sume screen editing characters are also printer control 
charactera, affecting the printer differently from the screen. Because of this inconsist- 
ency, it it usually not possible to print the aume output either to the screen or the 
Printer, unless all characters are upper -caag. 


chrdn Tl 


1 ponest) Enhanced printing {chr$(129) lor Return] Unenhanced printing 
chr${t0) Linafeed 

12 | chr$tt3) Carrlage return chrs{1dl) Carriage return without linefead 
17 | chr${i7} Rewer case ehr5(145) Upper case 

1B | chr$(18)) Reverse printing chr${146) Reverse off 

19 | chrs(19)) Top of form chr$(147) Sat top of form 

29 |chr${29} Skip space 
32 jchr$(32) Space 

34 | chr $034) Quote 




































chr${ 160} Shift-space; not # leading space 





chr$(255) User-defined special character 
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Enhanced Printing Most dot-matrix printers have this feature, which is quite easy to 
implement (in contrast to dsisywheel printers, for example, where the best approxim- 
ation to this facility is to overprint like this}, in Commodore's version, CHRS$(1) causes 
subseduent characters to be printed with an additional column of dots; carriage return 
or CHK$(t29) turns off this feature. This is not a doubling of character width for each 
CHRS(1), as it is often described. The diagram schematically shows what happens. 
Presumably, the printer's RAM ig loaded with a constant, which is decremented, acting 
as a counter for the number of columns in each character. 


oon ameeee we hemn ead seer tasen ans 
8 ae t@ nee eee eae eee 


UNENHANCED i 
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WITH’ CHRS$(1) «WITH CHRS(A)CHR$(2) —- WETH CHR$(1)CHR$(1)CHRS$(1) 


Remember that enhanced characters will fill a line with fewer characters than are 
required with normal-width characters. 


User-defined character, chr$(254} The single programmable chsracter available to 
users of this printer is defined by printing a six-character string into a file opened to 
secondary address #5. Subsequently, PRINT#4,CHA$(254) prints out the character, and 
PRINT#4, CHRS$(1)CRR$(254) prints it double width, and so on, The character apparently 
is confined ta 7 by 6 dots, so that descenders are impossible to get. The columna of 
dots correspond straightforwardly to the bit patterns: 


So the pattern of dots illustrated is printed by 
the string CHR$(2)+CHR$(65)+CHA$(73)+CHRS(90)+ 
CHRS$(9)+CHRS$(0). The example program below 
defines a character (made up of CHR$(65}s), 
puts this in secondary address #5, and prints 
the result as CHR$(254). This gives a rather 
unexciting pair of vertical lines, one row at the 
64 (top) level, the other representing 1. 





TOTAL: 265 73 90 9 0 
SPECIAL PRINTER CHRRACTER- 


18 OPEN 4,4 1 REM PRINTER CHANNEL 

29 GPEN 5.4,5 1 REM SPECIAL CHANNEL TO PRINTER, INTO WHICH .. 
39 PRINT#5, “AAAAAR" + REM .. WE PRINT A S~CHARACTER STRING 

40 PRINT#4, CHR€¢254>s REM PRINT THE SPECIAL CHARACTER 

$8 CLOSE 4: CLOSE 3 


In the U.K., the 'f' sign is useful. One example is CHR$(1)+CHRS(13)+"72M!" or you 
may prefer CHA$(9)+"7ItA!". Try these strings in line 30 of the demonstration pro- 
gran, replacing "AAAAAA", to get the feel of the procedure. 


Lower-case printing This is a probiem, The designers of the system don't seem to 
have realised the considerable similarities between ‘lower-case’ and ‘graphica’ modes on 
the screen (most characters, except alphabetics, remaln the same In each mode), In 
place of @ simpte awitch, similar to that caused by POKE $9468 with 32 or 14, and per- 
hapa an optional sat of routines to take accuunt of BASIC i's oddities, each lower-case 
line has to be prefaced by a cursor down churacter. Without the cursor-down, even in 
lower-caye mode the printer produces this sort of thing: 


Fie St EO OD A 
1. @fT UP STOCK FILE - ADD MEM RECORDS ONTO ERO OF FILE 


So that in order to produce a printout Ilke this extract: 













L) = -—. 

Orn S Taxis é Fentpans 9 
Hezor at go ieins Distrituticns M 
Statusn # Parel: “peareci 









Tho following print atetomionte are nocausury: 


i@9 PRINT’ -—-o 7. §QA—__——_—___- +... * a’ 
5 PRINT" IM @ALESs 2g MT JeCI2>"3Im OLAX SCL 3" JIM DREION, “396! 
98 PRINT" [MW JAZARD) "J8C1S2"3IM PRIGING “J9C16>"JIM-ISTRIBUTIONT “yact7>"J! 
95 PRINT" IW STATUS: "J8C102"DIn ePRPELS “766199"T1n ePAREZ1 "J#¢z02"2! 
Dd a nD al rn Ts 

@5 PRINT") SUPPLIER CODE: *J6(21)” WIReMRERERENIIER" 


Ps ee rae 
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The machine-code routine which follows is a lower-case LISTer. It is written for BAS- 
IC 2 ROMs. The alternatives are BASIC 4 equivalents. The routine is entirely relocat- 
able, except for the underlined 2-byte address, which must be reset if a relocated 
version ig to work. * 


.1 Q93A AQ 00 85 11 8512 20(2¢) A3 
+: 0342 €3) 68 68 AO 01 84 09 Al BS 
.: 024A SC FO 46 20 BL FF 20 E2) DF Wéer may muck POKG (6,129 Ger Vink ford 

-: 0352 €9C8 B) SC AA CB Bi SC OBA 

.3 035A C9 FF DO 04 BO FF FO 31 

; 0362 64 46 20(D9 DC)A9 11 20 83 CF 

036A (5 CA)A9 20 A4 46 20 FF | 46 BB 

«i: O372 20 €2 03 C9 22 DO G6 AS Address (0302) to be changed on reliccation. 
.: 037A 09 49 FF BS 09 C8 FO 11 

,! 0382 Bl SC DO 10 AB B1 5 AA 

-: O3HA C8 Bl SC_96 5C 85 50 DO 

.: 0392 B2 4C(83 C3)10 DACO FF BS: FF 

.: O39A FO D6 24 09 30 D2 38 E9 

.: O3A2 TF AA 84 46 AO FF CA FO 

.: O3AA O08 C8 B9(92 CO)10 FA 30 = B3 BO 

11 0382 PS CB BO 92 CO 30 05 20 

+: Q3BA (ISCA\DO PS 49 @0 DO AC 46 BR 

.: 03C2 48 09 CO CB DB 90 08 C9 

.: O3CA EO 10 04 68 49 80 48 68 

.: 03D2 4c GS CA 46 BB 


Other Commodore printers Cominedore offer two other printers, at the time of writing; 
a heavy-duty dot-matrix machine, and a daisywheei printer. Both seem to have been 
Produced in conjunction with other printer manufacturers, and are less distinctively 
CBM than might appear at first sight. The 8924 is a 9 by 7 dot-matrix printer with a 
head speed of 160 ch.p.s and capabie of producing multiple copies. It prints standard 
ASCII, i.e. no PET/CBM graphics. Or so at least the (rather scant) documentation 
gays; presumably, since true ASCII has upper and lower case different with Tespect to 
CBM, there Is some facility for mixed lower- and upper- case printing. its ST differs 
from that of other CBM printers; it can accept 1 secondary addresses. ; 

The daisywheel printer is a modified Olympia electronic dalsywheel typewriter. 
The 8026 is the keyboardless recelve-only version; the 8027 has a keyboard. The cost 
is simar to the 8024. The maximum speed of the unit (16 ch.p.a) is, by printer 
atandurds, very slow; a page like this one (without the type-face changes!) might take 
five minutes or more.? 

The 8026 and 8027 have many features found on more expensive machines, but 
as might be reasonably expected, theye are typically not so easy to use. Line feed, 
form feed and tabbing, for example, are all reiatively awkward. Moreover, several sete 
of ROMs have already appeared, which are (in gmail ways} incompatible with cach 
other, Some ROMs lack variable ling separation. The control commands are similar to 
thone of many printers, using ASCII control characters of CHR$(10} and CHiR$(13) 
for tinefeed and return, CHR$(7) for BEL, and in particular the escape charucter, 
CHR$(27), followed by a whole set of ponnible parameters. These include horizontal 
Spacing (10,12, or 15 ch.p.inch), tabs, direction of printing, and allowance for the 
type of printwheel. 


CBM ‘plug-compatible’ printers Because of Commodore's major market position in the 
U.K. It a not surprising that manufacturers have produced printers which ptug Into 
the computer without an external interface box. For example, Anadex have dona this, 
4nd thore arc a few very cheap Jupanose printers. The Epson MX-80 (though not tn 





Thie routine, published in ‘Micro’, is the work of Jim &tra and ie printed here 
with his permisaton, (The BASIC 4 awondmants are atralghtforverd ROM addroas changes; 

I have not teatad the remuit}. Jia Strawma ta active in the Central [lllaals PET Usora' 
Oroup, which publishes the 'Midnito Goftware Gazette’, = quarterly reviaw, The third 
*ditton of Quborne/McOraw-Hill’s ‘PET Guide' is edited by Jim and Nia wife. 


"CCN, Sept.'@1, glvea some information on Commodore's datayvhee] printers, 
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this ‘very cheap’ category) is widely preferred to CBM's printers. These machines, 
many of which were scld when CBM printers were subject to delivery delays, are 
often non-Commodore in fairly subtle ways; they may be advertised as having graph- 
les, but the character-set may be non-CBM; the handling of print statements and 
formatting is very likely to differ from Commodore's, since mimiery of the entire range 
of secondary addressing and other featurvs would involve a Jot of work. Often this 
makes no difference; only when a program is rum on & new machine (i.e, one which 
uses different conventions) will any problems arise. 


Non-C@8M and non-plug-compatible printers Many of the major names in printers make 
nachines which cannot be directly connected tu PETs; Qume, Ceatronics, Diablo, Spin- 
ariter are examples. Centronics printers have their own standard: other standards 
melude the ‘current loop’ and the 'K$232', a serial interface which accordingly needs 
few wires, These need ‘interface dDoxes', devices which Plug into the computer and also 
nto the printer. An interface box may need its own power supply. There are a few 
\azards to watch for. The most important, yet again, is the treatment of upper and 
Ower case text. The switch between modes within the computer cannot generally be 
letected by an interface box, so that, unless this is filted witr a switch, you may 
‘ind that only upper-case text, say, can be ersily printed. Probably some sort of con- 
rersioa routine will be provided, perhaps a painfully slow one in BASIC. This is prob- 
ibly something most users could do without. (t is occasionally teue that an interface, 
vecause Of a design oversight, won't transmit certain characters, such as ‘Escape’. 

As an example of the methods of programming such printers, which rely on ASCII 
‘ontrol charucters rather than secondary addressing, look at the following short BASIC 
srogrim extracts. They epply respectively to a Qume and a Centronics printer. There 
s no standardisation in the characters following 'Escape‘; the specimen printout shows 
1 Qume printing data sent from a program designed for a Centronics machine. Note 
hat on appendix as o complete list of ASCII characters, mnemonics, and ‘heir mean- 


ngs. : 
1000 OPEN 4,4: PRINT#4,CHRS(12); : REM QUME. FORM-FEED... 


1010 PAINT#4, CHR$(27) "E10 CHRS(27)"L04";: REM HORIZONTAL SPACING 16/120 = 1/12 


INCH; VERT. SEPN.=4/48 = 1/12 INCR 


4100 OPEN 4,4: CMD 4 : REM CENTRONICS 


A1LO PRINT CHR$(27)CHR$ (20) CHR$(27)CHR$(15}: REM COMPRESSED AND ELONGATED CHRS! 


axoGu Kir gE 4,mu i] 3 & 
NEO We dAu eg? é€ Ww) 5 t o 
NE OO Gna tie eB? € a a ? ‘ 


'rinters: a Summary Users looking for good-quality printing. without the obviously 
omputer-produced appearance of dot-matrix printers, have iittle other choice than a 
alsywheel or modified golfall printer. If there is a definite need for speed. ard many 
opies of an original, or 132 columns per page, then a heavy-duty printer will be nec- 
ssory in the first casus, and a wide platen or programmable narrow charecters (e.g- 
6.7 ch.p.inch) in the second. Paper width(s) and type aay be restricting factors, 
ince many machines aren't versatile in their paper-hondling. If an interface box is 
ecessary, be sure a good one is available, ft may be nucusaury to ensure that a 
rinter can operste with several different typea of computer, Because of the chance of 
nexpected progrumming difficulties, It is advisable to teat any cambinatlon of hard- 
are whieh is new to you; mixed upper- and lower-case text, and Rraphles if these 

re baportant, wre likety to be problem arear. In thia way, wit luck, a good, faust 
yatem can be put together, in which fundamental atma af the syxatem have nal been 
vertooked. Muny users, of course, sluply buy CBM equipment. Current market 
ipveyn may (or may not) suggest belter buys. Many such sauryeys though are not 
ery thorough, and eee Mite mere than agsembinges of information provided by avert: 
eri, da practice, § suppesda dealer advice and axchange of recommendations between 
tends and colleagues are about equally lapertant forces determining: faa ehalee of 
irdwure, Thare ia one other, perhaps obvious, point: be suri: Lat paper, ribbons, 


gare fuses, oxtea Gojsywheela and ao on aren't loo Inacceyalul:, and that maintenance 
avutilable if tt's neaded, 


* 
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BA the Mee, 


modore'’s Mudem (the '8010') is wired as fEEE device Fe, and can be hens pala tg 
ae ith the normal INPUT #/ PRINT# commands to logical files with secon ary ea ie 
Hy “The function of @ modem (‘modulator-demodulator' ) is tu process inset tty ial ai 
it i output from a computer into a form suitabie for transmission to en ate Dias ss 
which secon vocts it into data to be input by a second computer, In this at pone 
pi rams can be transmitted across country or between continents. Fe eet Eee 
aate is formatted with start bits , a parity bit, and framing by oc a Braue 
hip, sent out, and decoded by a similar chip at the other end. Hig ay a eae! 
teanster are possible. The guid is an ‘acoustically coupled moden, hig wee tg i 
sound sent by normal telephone lines. (It hg chr i approval in the U.R.}- 

in conjunction with the ’ ; aa ite ol 
Me cave 2 a eanne Taig agvslopment aida - can be received in this Ae 
thay can also be sent through the post, this may not ba iad Pipes arate neg 
Se ee Ter 1 oupani i eall ie nay Seacey ‘Uaeful. since data which 
subset of a company's data, WHS E et n 
Dent poverwler need to be re in al be aesnaaied ay de Ur ae o 
everal points related to the actua: opera , f 

mind, th ae speed is 309 baud, presumably meaning an yee Gaara 
bytes per second, At this rate, a 40-column screen will oles a Larges seed oe 
and an B0-column screen i minute. This mey be tao slow for so i hat pete ae 
likely to be difficulties over the transmission of mixed upper- ae sh ae eer 
alphabetic characters, since these are not consistent with the bs eaeaRans cing 
software is needed to process the transmitted data. and Lasts piles UP seaihasenbt 
may be needed to correct disparities of convention betas) the Se tor Dace 
ercial products are available incorporating one or both of these i ’ 
to read and store Prestel pages.” 


8.7 The keyboard. 


i i uite the 
Introduction and physical descriplicn The keyboard is not @ eeacgeeaanatg 7 i 
same sense 9s the other items of hardware discussed in this chap ma - ie 
intimate connection with the computer. [t resembles a reais eto biacagelae nee 
i i the h : ' J 4 
is concerned largely with programming [fh ; on 
Easel pean ponte uf the uchs of keybaard ta sereen which usually happens except w 
os Sipser keyboards are equipped to handle most ASCTI LUbbancaayee ries 
the exception of the control characters (not needed) and the more i tinvennne 
symbols (curly brackets, underlining, single quotes sloping aaa a leat oh 
raphics ehnructers, but in the "business machines’ the decending Is dc) ; a ibe 
fice, ra excluded to some extent. The keytwards have evolved in Lg aaa tin ‘ 
trom the endl tiny rectangular array of keys to the eid tai ad ed bins a Sipe 
nuineric keypad, and with punctuation characters ohtained by 6 a enti ee 
1 and soon). All inelude screen editing keys and the stop/run li Ent: theee 
ifically CEM functions. TAB. Esc, and repeat occur on the 12 ine tee ain vey wae 
arg some minor differences: aome 3000 series mochines’ keys are mar 
7 natanece , dine 
vou fevtnele are very relivbia: soneunee an eriaae ay ine te et Mi 
‘ 4 : free from software : : 
if tt and clenned. They are rot quite ; ; pera 
Sor ment hinsil alrendy; In BASIC 4, the 8032's right shift with reverse an ' 
nyHe ep wrong character. ; is : 
ne ich ach BVs slows tho sercen serail Gt second iniey Bt an 
Hs 12 ingh modets, the left arraw slows ne ratling Had ot t quuse sore! , 
pause indefinitely. until one of o pane of other keys is penne om i ae tac 
UAE: Shere are a feu iveumpalibililies Ghat may dos: at oe of Ha ulgaih soins ae 
Ath 3 1 " itin lop rlebt) as Cle var!) 
ey on the BOd2 16 In the anme poxition ¢ chet ! eh 
Neale a ‘it Is patter eary te dowd amd rag 4 sk peagrain Inastoned ie aan es 
were “pon user in necustened ta the orrly Inyout, Thin of course wilt crase eny 
ole eam In meniery, ake Pas 
bite Canin baie have no inballf reset key, Uhts haa Rar ay Vee 
beige developing qichine cate. Hoa eeash resutts, tie muchine fin ts is 
is shay 








5 a6 terwinnla shich inc tudeu 


. are - cr ol srumpa ter 
ecey aug. (ML hea an eetiels by PB Barker on slercey CON of Cre. HL bas wm 16 


scan eaplesstory fdatadd ack peograas relevent fr the 8j)0, 


page canteen ace tint aod ave Uariud Peerage. 


Me peg ae tae lle Th 
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md reloaded ~ if the programs were saved, that is. On the other hand it preventa 
| program being wrecked in mid-run, something which is possible on (say) the Apple 
1. (VIC haa & reset, using the NMI line}. See the next section (8.9) on methods of 
tonstructing reset keys for PET/CTBMs. 

Physically, the keys are mede of tight plastic, surmounted by a grey or black 
tey bearing the legend. The tops of the keys can be levered off and replaced; there 
38 feeble-seeming spring inside esch one which prevents the contact at the base 
reing made until it is pushed. As we shall see, we can redefine the keyboard decoding 
unetion, so that nen-standard keyboards, such as the ‘Dvorak' non-QWEARTY layout 
‘att be tried out. 

A reliable way to disable the Stop key, but atil? i 
s to use a guard oie the key. The agra rtaniere cer ap ee 
‘plotted by a PET!) shows the general app- 

‘arnnce and dimensions of such a guard. (The 
igures may not apply to all keyboards). A 1s5cm 


ectangle of stainless steel, and access to pnee 
xetulworking fucilities, are necessary prelim- 
Navies, The hole in the top allows the key 
o be pressed with a pencil or biro. I have’ & E 
ound this systen completely reliable, “9 : 
N me 
o> 


tASIC and the keyboard On the subject of 
lisadling the Stop key. the most well-known 
lethod is to use a simple poke: 


POKE 337,139 {BASIC 1] 
FPOKE 144,44 [BASIC 2] 
POKE 144,88 [BASIC 4] 


!ASICs 2and 4 can be simullancously covered with POKE 144, PEEK(144)+3. This papular 
‘ethod has the drawback of turning off the clock, for reasons we shall see. Also, any 
peration changing the interrupt vector (tape operations for example) is likely to re- 
tore the normal interrupt with its test for Stop. Poke the identical value minua 3 in 
ach case to return to normal operation. 

The keyboard is treated us device #0 by the operating system; then come the 
agsettes and the sceven (#3), before proceeding to the IEEE bus. We can open 2 file 
> the keyboard: , 

OPEN 1,0 :REW OPEN 1,0,55,"XYZ2" IS SYNTACTICALLY OK, BUT HAS NO EXTRA EFFECT 
nd now, in program mode, we can INPUT#L and GETA1 from this file, (PRINT#L gives 
Q error message). This can be used to give rudimentary input protection; if Return 
i pressed with no other entry, [NPUT#1 returns CHIR$(0). Commas and other punctu- 
an separutors won't now print 7EXTKA IGNORED, because a file is considered to be 

Thia same (input protection) effect can be more easily got by a simple poke, 


POKE 3,X (BASIC 1} POKE 14,X [BASIC 2] POKE 26,X [BASIC 4] 


here X fg any non-zero value. Surprisingly. thl4 method has never yet been docu- 
ented, so far ag I know, 

GET is the BASIC function which tukes characters directly from the keyboard, 
a we have seca in chapter 4, this is a relatively easy woy to modify keyed input, to 
rola the linltntions of INPUT und to code keys for some purpose, without echoing the 
‘wracter to the sereen, ag in this simple example: 


20 GET X4: TP X$="" COTO LO): REM GET XFYBOARD CHARACTER (WAIT FOR KEYPRESS) 
20 fF X$>e"A" AND XSc—"%" THEN PRINT “VALPUAHETIC?H” 

30 TF X$>=e"0" AND X¥e—a"GE" THEN PRINT “NUMEH EEE 

40 If ASCCAS}a2S THEN PRINT “(CLEAR]" -HEM DAFINE RETURN KEY TO CLEAN SCHERN 
$0 PRINT "OTHER": GOTO 10:REM IGNORING SHIFT CHARACTERS, TO SIMPLIFY PROGHAM! 


ASIC band 2 have a fenture (acemingly carricd over trom uon-PET HASIC by Mlero- 
MO} In whluh input af CHESIS), ‘Shift Int in ASCUR. eanses no output to appear on 
wosereen, In fret, thls character doesn’t exiat an Ci keybourda, but the auppresa- 
ib featire remoink: POKE l00,% (BASIC 1] wad POKE 13,0 (HAs IC 2} where X executes 
7 prevents PRINT from operating, 

There sre differcaves between ftruoh ASCH) and PET /CTIM a somevrbut moelifieed 
reajon, but these are oily buporlaat when communicating between jnachines., A lille 


wae 
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of true ASCII characters is printed in the appendices. 


ROM: how the keyboard is scanned When a PET/CBM is operating normally, its pro- 
gram is interrupted at regular intervals and a subsidiary routine performed; this pre- 
cesses the cursor, turns off one ov both cassette motors if they are on, and scuns the 
keyboard for a keypress. If a new key is pressed, it is added to the keyboard butfer, 
unless this is full, If it is, BASIC 4 ignores the key, BASICs 1 & 2 cancel the bufler 
and start over. Let's examine this proeess in greater depth. : 

Firstly, how many interrupts occur per second? We can time them approximately 
with BASIC and a 6502 subroutine: Type SYS 4 to enter monitor; now type .M O2ZTA 027A 
.t O2T7A EG OO 4C xx xx where tha unknowns are the (RQ low and high bytea respectively 
as they appeared on entry to the monitor, Overwrite I[fQ sith 027A and enter .G a004, 
which causes the interrupt to execute the short routine; it increments locatlon $00 
with each interrupt. Type .X and enter the BASIC progran 9 IF TI-TcGQKHTO and 
APRINTPEER (©): T=TI:POKE0,0:COTO vhich i# written to run es fust as possible. The 
contents of $00 after 1 sccond are printed out. The value ig about 60 for B-inch screens 
machines, $0 for 12-inch screen tachines. 

When aon interrupt is generated, the 6502 finishes its current instruction, seves 
values on the stecz, atid jumps to the address in ($FFFE). if the interrupt is not 
masked. This address is E468, EB#18, and £442 in BASICs 1,2. & 4, If these addresses 
are disassembled from, it is clear thal A,X, and Y are all saved, for later revovory: 
this means that the interrupt program is entirely separate fram the normal pregram. 
Moreover, the status register is examined to test for a BRK, signalled by the vreak 
flag, or a standard interrupt. In the furmer case, the moniter is entered (except in 
BASIC 1), which is why SYS 4 or SYS 1024 or SYS of any location containing zero 
causes @ break entry (signalled? by *B) to monitor. The interrupt jumps to an address 
held in RAM as two bytes; this address can be changed, so the programmer can write 
new interrupt servicing routines (like the small-scale example above which increments 
$00 at each interrupt). 

(#90) holds the address of the interrupt servicing routine; this is the address 
printed under IRQ when .R is entered in the monitor. This is ($0219) in BASIC 1, 
Thus fifty or siaty tines per second the interrupt takes place and the code pointed to 
by this address is executed. This code - at E665,FE 62h, and F455 in BASICs 1,2, & 4 - 
is of some length, and takes up a measurable time, perhaps 7% of the total, to per 
form. This time can be saved by tempororily turning off the interrupt. 

There are four parts to the interrupt servicing, which those interested can see 
by disassembling the approprinte cole and examining it. The parts are: 

(i) Update the ciock (TI and TI% locations) and check the Stop key. FFEA is a 
kernel jump command which carries this out. BASIC 4 (12-inch screen) includes a 
patch which increments the clock an extra ‘jiffy! every 5 interrupts, #0 the timekcep- 
ing Is irreyular. See TI in Chapter 5 on the ‘correction clock’. 

(il) Service the cursor by reversing the character under the curser whenever 
the countdawn becomes zero. 

Gii) Switch off the cassette motor(s), unless 4 flag is set. 

(iv) Sean tho keyboard end perhaps update the keyboard buffer. 

Of thease, (iv) is the most intricate and takes the longest time. A table on the next 
poge liste all the relevant RAM locntions of these operations Ia an eanlly -refercaced 
form. Som: - the screun processing and the clock - ara nut dlicetly relevant to the 
keyboard, but a single table ia more conveniont than several smaller tubles, 

To understand the keyboard scauning process, we must briefly consider the 
6520 chip (PIA, or ‘Peripheral Interface Adapter’) which handles the hardware side of 
it. Chapter 14 mapa out and explains this chip in greatur detail. The PEP/CRM has 
Iwo of these sips; the (iret, (RIAL ppears at E10 - Esta. The locations which 
contral the keyboard are Dated : 









esto cz9009) [| TT 2 PORT A 
eviz csyane) f° TT 7 LbaAsy ft } PORT A‘H CONTROL HEGISTER 
mea csoa1os [Rew input 7 (a PonT A 


PORT f° CONTROL REGIATER 


ess oany (ET meet Jee 
Whee &, Poet Aba oe Bla conlenta contiques the “port tus faput or cutput, On ‘awitchon, 
bliin 9-3 uf Port A gre conftiyurcd es output, aad bite 4-7 as fuput. by atoring #OF in 
A. Port Mods ennflygured for Input anty, 

Then 0, the latercuyt ia dtaabled; this turas off tha keybonrd acanning process, 
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E812 iy wired so that ai! 8 bits are normally t, The pattern of bits 0-3 of E810 deter- 
mines which (of 9) rows is examined, To scan the entire keybourd therefore requires 
a luop to change E810's rightmost bits from 1 through 9, testing E812 each time for a 
zero hit. which indicates a keypress, There is an elaborate loop in the interrupt ser- 
vicing routine which shifts Ure contents of F612 rightwards, looking for a zere, and 
continues this process while changing ERIO. When # zero is found, the corresponding 
Sey is found from the keyboard decode table. (See Chapter 15 for a diagram). It is 
quite easy to mimic this process in BASIC {there is a routine in 'PET Revealed’). The 
short wachine-code routine shows which keys belong to which ‘rows’: 


: O27A AD OO BD 10 ES AD 12 ES 
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START LDA #00 


STA E810 -: 0282 AA AD OO 4€ xx xx 
Lpa E812 

TAX Q INPUT "ROW (0-9)";R 

LDA #00 1 POKE 635,H: SYS 634: COTO 1 


JuP DCOF/OCD9/CFE3 [BASIC 1/2/4] 


This cade and its BASIC driver prints out the contents of E812 in decimal; if a single 
key is pressed in the row being scanned, a value 127, 191.223, 239, 247,252,253, or 254 
will be printed, No key is shown by 255, Each of these figures has a bit pattern of 
a single 0 within seven Is (OL1L 1111, 1lOUL 1111, etc.). The figures correspond with 
thosn shown in the keybourd decode tables; for exumple, 40-columa BASICSs inctude 
=, Stop,<,Space,{. and Reverse in row 9. This row represents the normal state of 
E8t2 (on switchon and aftur the keyboard scan) which is the reason that LDA E812 
is used us a test for the Stop key, and can also be used to test for the otter keys in 
the row. Thus 'Wordcraft' for example uses the Revyersc key and the Step key to con- 
trol its modes. Note that the rows are not arranged in straight lines on the keyboard, 
but are wired to select alternete keys (roughly). 

The keyboard decoding matrix has &¢ entries, 10 rows of 3 ASCII values, some 
disused. The tadle is scanned from the end to the beginning. Note that the shift key 
is signalled by 6G. 





IRQ Servicing - Keyboard, Screen, and Clock Locations. 


Locations ; 

Description BASIC t BASIC 2 BASIC 4 
byte clock 0200-6202 8D- PF 
Correction (2 bytes) 0205-0206 99-9A 
Stop key test (copy of E812) 0209 9B 
Cursor - Q-off, 0 means on 0224 A? 
Cursor countdown {from #$14} 0225 Ag 
Blink flag - QO-unreversed, l-reversed | 0227 AA 
True character under cursor (pcek) 0226 AQ 
Displacement 1-80 from start of table 9223 A6 

for 255 if no key pressed} 
Shift key - O-off, lvon az04 $8 
Displacement 1-80 of previous key, for; 0203 97 

comparison with 222/AE/A6 12" 40 col: 
Number of characters in keyed. buffer | 0200 2 9E ieee 
Length of keybourd buffer E3 O3EB 
Keyboard buffer G20F-O02t8 | O26F-0278 026F- 
Repeat - 6728 off, 128+ on E4 O3EE 
Repeat countdown Es O3EA 
Change of key Indicator E6 O3IE¢ 


Eass 
E609-F658 €40-cot) 
E6D1-£729 (80-col) 


IRQ SERVICING ROUTINE 
KEYBOARD DECODING TABLE 


E75C-E?ABj E6F 8-E 74? 





Hit 2 of the control reyivters of the PIA controls the data directlon of the porta; by 
setting the bit low and entering new vaiueR in port A or port B, anomatar: reuults 

can be oblalned., PUKE $9409.09 Is a simple HASIC example; the full eange of rows in 
no longer obtainable. Similarly. If the cassette interrupts are in uss, poklng Esid Cin 
machiny- coda) wlth #XA In place of 4X9 disables the Stop key. At thin polat, wa can 
pause to examine Stop key dinabting: the uzual POKE montioned previously works by 
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redirecting the interrupt vector to point 3 bytes beyond its normal point: in this way, 
the first instruction of the IRQ servicing routine (e.g. JSR FFEA) is skipped; thus 
the Stop key is disabled and the clock turned off, Another methud is to store #FF in 
the location which copies £812, and which is used to test for Stop: 


JSR FFEA; UPDATE CLOCK/ COPY E612 FOR STOP TEST 
LDA #YF 

STA 9B ; COPY OF E812 SET TO ‘NO KEY‘ 

due E458; CONTINUC NORMAL INTERRUPT 


This routine, for 4?column BASIC 4, when inserted into the IRQ, behuves exactly like 
the usual interrupt, except that the Stop key, when pressed, is overwritten. Thus the 
internal clock runs nercally, while Stop is disabled, 


The Keyboard Suffer It is well-known in CRM circles that the keyboard buffer can be 
programmed independently of the keyboard. (The process is sometimes described as : 
‘a program writing itsel!’ with certain applications), For a destription see section 4.1.9 in 
Chapter 4, The keyboard buffer can be watched as it queues charucters. Chis is worth 
doing to understand the process. Enter one of these routines: 


‘AS 9E 09 30 8M 0G 8G AG :A5 9E 09 30 BD OO 8D At 
10A BO GE 02 99 O02 80 88 :E3 BS GE O02 99 02 30 48 
.:024A DO F7 4€ 2F £6 *DO F7 4C 55 E4 :DO F7 4C 55 FA 

BASIC 2 BASIC 4,_40-COL. BASIC 4, 80-COL. 


Then change the [RQ vector to 027A, The keyboard buffer, and the number of bytes 
in it, are displayed in the top-left of the screen. (Lower-case mode will make then 
more readable}. A short routine of this sort: 1 GET X$: FOR J=0 TO 1000: NEXT: GOTO 1 
wit enable characters to be queued up from the keyboard; they are then removed at 
ebout 1 per second. The separate routine for 12" screen BASIC 4 allows for the fact 
that the buffer is not fixed at the normal 10 characters, but can be varied by poking 
$E9 (2227), Characters remain in the buffer until they are fetched by GET or INPUT, 
or until the buffer is celeted {in BASIC <4) when more than 10 characters are entered. 
Poking the number of characters to zero in effect clears the buffer, giving the some 
effect aS 100 GET R$: IF X$<2"" GOTO 100. Conversely, poking the number of charact- 
ers to some non-zero valuc makes them available to the system, Try: 

10 FOR J=623 TO 627 : READ X; POKE J,X: NEXT : REK S BYTES IN KEYBUARD BUFFER 

20 POKE 158,5 : END ; REM SET # SYTES = 5 

30 DATA 72,69, 76,76,79 


The five bytes are printed out by the system when the program ends, exactly as If 
they had been keyed in. Replace the duta statement with 30 DATA 76,73,83,84,193. 

Now the word 'LIST’ followed by a carriage return is entered in the buffer, and the 
command is carried out. There ure several examples of this type of rautine in this — 
book; see for example DELETE In Chapter 5. Note that BASIC 1 has different locations 
(525 tcharacters, 527-536 = buffer). 


(027A AB SE 09 30 &D GOD 80 AO 
10282 GA BO GE 02 ¥9 02 80 BB 


Examples of programming using the Interrupt We shail see now how to carry out some 
ambitious routines involving the interrupt. First. we shull consider software repeut 
keys, These are not needed in 12 sercen CBMs, which Include rupeating keys ag a 
stendard fenture. But is. the other models they are useful. The principle is not very 
difficult; the keytoard nomnally prevents automatic repeating by comparing the key 
Pressed during a scan with that pressed before. If they are the same, nothing ia done. 
Therefore, If our program Intercepts the interrupt and sels the previously recorded 
key value te 255, the key Ja reinput to the buffer, Seo the next page for exemptes . 
The second example moves the entire interrupt routine Into RAM, where it cin be 
mMoMlied fruely. For exemple, the rate of cursor Mesh con be changed, ang this can be 
A useful reminder thet a non-ainandard keyboard te in use. In this way the keyboard 
can be madified, as tmenticnnd before, perhaps te provide a hex keypsd, or # Dvorak 
typewriter, or to une one or both shift keys as xpecial function keys. The third ex- 
ample by o xingle-key RASIC ontry routing; one shift key, plus a key, enters an en-~ 
tlre keyword, Thin principle can be generalised, ao that for example a key may print 
any predeflued atelig: te the sereen, nnd some commercial apftware atid toolkits can do 
(ils. Phe: proceasing t. of course virturity tastantanevus; alinilar effects can be pot 
in WASIC, whth GET 24: TF x$0°K" THEN X$-"SOMETIING ELSE", tut thla ln alawar, and 
takes up program space, Moreover, Individual Rey (e.g. both Shift keya) cannat be 
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distinguished from BASIC. 


Software repeat keys (for 8” PET/C8Ms, BASICs 1,2, and 4) 
REPEAT EEY FOR BASIC 2, 


O27A LDA #44 ; INITIALISE +i O27A AQ 64 85 90 AG 02 aS Bt 
Or7C STA 90 -: 0282 60 EA AG FF CS 97 DO 05 
O277 LDA #92 Oz8a AM GT) BD 83 02 CE a3 02; Malay, 


O26C STA 91 : 0292 DO OB 65 97 Ad G5) SD 83; Repeat, 
0242 RTS > 029A 02 AD (OI)8S AB AC 2E ESECursor. 
ner mh WEF + REPEAT 7 SVS 634 INITIALISES THIS REPEAT KRY, 
O284 Cur 97 Notes: 
O28 BNE O26F (1] Varying the three bytes contrals the 
O2RA LDA £14 ; Firet dolas t/3 sec. time taken before repeating starts, the 
O28 STA 0283 rate of repetiticn, and the rate of flash 
O2aF OFC 0283 of the cursor. For example, PORE 1 into 
0292 BNE O29F each for the maximum repeat rate of 60 
0294 STA 97 characters per second. 
O296 LbA #05 ; 1/12 gece, between [2] .M 0090 0O90 trom the monitor can be 
0298 STA 0283; repsota used an a method of turning ‘repeat’ on 
O2GA LDA #03 ; 1/20 sec. between aod off, and redirecting IRQ generally, 
029D STA AH ; cursor flashes {3} If the casvette buffer is corrupted 
O29? JM? FE2E while the repeat is operational, the 
interrupt will probably crash. The 
exception is for tape activity iteelf, 
which resets the IRQ and so dissbles 
the repeat. 
BASIC _1: Old ROMs differ in (1) IRQ vector, (14) IRQ servicing Incation, 


{iii} keypreas indicator location, and (iv} cursor flash countdown. 
These are: (1) ($0ZTA}, (ii) $6685, (iif) $0223, ond tiv} g$o2zzs, 

The same logic may be used) but the renulting code tnevitably occupies 
gore apace. The cassette duffer #2 vernion is this: 


O DATA 269,70, 142, 26,2,169,3,141,27,2, 96: REM INITIALISES 

i DATA 0,169,285, 205,35, 2,208, 5, 169, 20,141.69, 3,206,69,3,208,13,141,35,2 
2 DATA 169,5,141,69,3,169,3,141,37,2,75,139,230: REM REPEAT KEV DATA 

3 POR J*876 TO @70: READ K; POKE J,K: NEXT: SYS 826 


can he turued of € by poking $£4,¢(22h) with a value<126 and vice versa. 

And the repeat cursor flash rate is controlled by the contents of $E5). 
40-colwen machines are aimilar to BASIC 2, except that the IRQ deatination 
fa different: so substitute JMP 3E455 and ... 4C 55 £4 in cach BASIC 2 
Prograa on this paga. 12° werson 40-colum models have some differences. 


TINY AEPEAT KEY. (BASIC 4) 


By using & aero page Btore, and having only one delay constant, ‘repeat’ can be 
reduced to 19 bytea only, This 1s tho shortest routing I‘ve been able to write, 
and f include it for those who llke little routines: 


Loa arr Ag FF CS 97 DO Og 83 OF 
Cup 97 Ao(10}85 99 C6 00 FO F64 Delia Constant 
HOE +4 40 2E 96 
STA a7 
LOA #10]; doley constant Une .M 0000 0080 to pointe ($80) to the 
STA OU |; zero page story atart of this routines. 
DEG oe : seen: Mas obheret At fawi rateo of repeut the cursor vill 
HEQ -10 5 declmokt branch flush too elorly te b t iwi 
yu? Le2K us etlowly to bo slways viaibte. 
MENT 8 oe ears A SNe SAY INT I AN ORD AI PEE IY RR IEE SAC ET Sree Lt oe te 
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BASIC RELOCATING LOADER TO FNASLE USER TO DEFINE RIS OWN KEYBOARDS (2.0. HEX Pip). 
BASIC 2 ; 

O PRINT’ (CUEAR} (REVSJLOADS USER-DEFINED SPECIAL KEYBOARD AND PROTECTS IT IN TOP OF M 





IO L » PEER (52)4256*PEEK(53) 2 Tle: REM L IS CURRENT TOP OP MEMORY; T1 STORES IT 
15 T=<L - 302: AEM WE RESET TOP OF STRINGS TO ENABLE: SAPE INPUT OF CHARACTERS 
L6 LAX= T/256; LEZ = T - LH2*256 
1? POKER 52,LL%: POKR 50,LL%: POKE 48,LLZ: POFE $3,LH%: PORE S1,LHZ: PORES9,LAS 
20 FOR J = $9207 TO 58926 STHP -1: PORE L=l, PERA(J): L = L+l: NEXT 
30 REM MOVE INTERRUPT RUULINE $E62E-SE747 TO TOP OF MEMORY - 1; & = LOWER LIMIT 
40 KT = Le2Ol: REM THIS (S THE ZEYBOARD-TO-ASCII-I[ASLE POINTER IN RAM (RTS) 
$0 MX = RT /256: KLZ = ZT - 256*RNZ: REM LOW AND HICH BYTES OF NEW TABLE 
60 POKE L4+L11,KL%: POKEL4+112, KHZ 
70 POKE L4160,KLZ; POKEL+161,XHZ 
80 REM BOTH REFERENCES TU TNE KEYBOARD TABLE CHANGED TO POINT TO RAM, NOT ROM 
90 PRINT" (CLEAR) (REVS) ENTER *** WHEN YOUR KEYBOARD IS COMPLETE": REM COULD BE OTHER £ 
XLT STRING 
100 PRINT [DOWN] PRESS KEY TO BE CHANGED [REVSJOR[RVSC] ENTER 
1Ol INPUT"’[TS ASCIL VALUE, LIKE THIS: ¥14";RKS :REM TO DISTINGUISH 3 FROM CHRS¢3) 
102 IFKS="&42"THEN SOD 
105 K*ASC(KS) ; REM LF A VALUE AAS BEEN ENTERED, NEXT ae FINDS CORRECT K 
; K ay" LEN{KS)>L THEN K*VALCMLDS(KS, 2 
120 gd at ae fee CoS veo THEN Nextt PRINT 2 nevsi Not Founp": GoToi0d 
130 3 = S$ + RT : REM J TS THE POSITION IN THE ROM TABLE AS RAM TABLE MAY VARY 
{40 REM WE NOW HAVE POSITLON (=J) OF SOUGHT KRY IN RELOCATED TABLE IN RAM 
200 PRINT" [DOWN] PRESS KEY TQ REPLACE (REVSJOR[R¥SO0} ENTER 
20) I[NPUT"ITS ASCII VALHE, LIKA THIS: Via"; R$ 
202 LEKSa"* Ak" THENSOO 
205 KeASC(KS) ; 
240 IFLEFITS(XS, L)e"¥" AND LEN(K5)>1 THEN ReVAL(HIDS{KS,2)) 
220 POKE J,K :REM REPLACE THE PREVIOUS KEY (1 THE RAM TABLE WITH THE NEW ONE 
230 GOTO 90: REM tow DO THE NEXT CHARACTER 
500 REM FLNAL ROUTINE: POXE 2 ROUTINES TO CHANGE INTERRUPT ADDRESS 
510 DATA 120,149,46,133, 144, 159, 230,133, 165,95 
520 DATA 120,169,46,13%, 144, 169,230, 133, 145,96 
$30 FOR J = L-20 TO Lel: READ X: POKE J,Xi NEXT 
540 L = L-20: REM NEW LOW MEMORY LIMLT = START OF EXIIRE ROUTINE 
§50 PRINT [CLEAR] [DOWN] SY¥$"3L; "TURNS ON THE NEW KEYBGARD, AND 
560 PRINT’SYS";L4lOc"RETHRKS TO NORMAL KEYSQARD 
$70 POKE L+2, (La20}) - N66 ¢1420)/256)9256: PUKE LFS, (L420) /256 
$80 REM TURN-ON ROUTINE Wii. NOW LOAD THE CORRECT INTERRUPT ADDRESS. 
5 ITT EL AVE FROMUEOTONTE 
395 PANT ‘rege {$";: COSUBGO0: PRINT " TO $";: L = Ti + GOSUE600: PRINT "}" 
59% END 
599 REM ### ONR LINE DECLMAL TO HEX CONVERTER #48 . 
600 L«L/4096;: FORJ+ LIOG:LZ=L:LS=CHRS (484L +(L%>9) #7): PRINTLS; tL L648 (L~L2) 2 HEAT AN TURN 
Modificattons for BASIC t 
419 Le. PK(L34)4056ePREER(195)0 Ti#Le REM L £S CURRENT TOP OF MEMUIRY! T1 STOR 
FS 
15 Te L - SI9:KEM WE RESET TOF HF STRINGS TO ENABLE SAFE 10PUT OF CHARACTE 
RS 
17 POKEIS4¢LiXs POKER LB2-+LLX+ POKEISO+ LUX) FOKELSS+LHe1 POKEIS9, LH%« POKEI3L 
tHE 
20 FG Joe $990? TO $9013 STEP -15 GQePERK(S)s POKE L-1, Qi Lo « L-13: NEXT 
49 XT « Le2ids REM THi3 1S THE KEYRUARN-TG-AICII-TARLE POINTER tN RAM (RTS? 
$0 POM LetSArKL&: PUKE Lei S%s KHE 
70 HOKE LetO7eKO0r FORE Lor Aas KX ; 
120 FUR Sos 2 TO BOLIF FEE ¢%9227¢3) ©) K THEN NEXTI PRINT “CRVSINOT + QUNT 
t GTO La9 ; 
DLO FATA £202 169) LGe Lab 2Ge Ze LAD) BV 14d, Bey Pe FO 
LOD TATA SPQ LGD LSD LS Poe Pe LOPs P80 LAL Phi 2G 
S40 FN Sos eva TO Lola EAL ke PURE Je Xt NEXT 
S40 toe 1. 24a REM NEW ODOM MEMtney COMET © START OF ENTIRE ROUTIVE 
200 PRINT CCORROCUUMM l¢S La TURNS ON THE TW KEWROARD AND 
[OO FUINT “SYST La Le EE TURNS TO NORMAL KEYHOALD 
SPY POKER Lots UL RS4) - INTOCL #24) 256) 8 Sht POKE Lave (L024) 256 
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FINE KEYBORRO FOR @832 ONLY :— ; 
RINI"CCLRICPYSILOANS USER-CEFINEO SPECTAL KEYGORRD ANQ PRUTECTS IT IN TO 

FOF MEMaRY 
. z aaa ae ill cc Ti=L: REM L iS CURRENT TOP OF MEMORY; T1 STORE 
T : L ~ 736: PEM WE RESET TOF OF STRINGS TO ENABLE SAFE INPUT GF CHARACTE 

[3 
He @ THESE s CLA = T - LHkesd 
ae Se,-Lt%: POKE 85,LLa: POE 49,LLé¢ POKME 53,LH%1 FOE S1,LH%1 POKE49,L 
“DOF. Jr S9le9 TO S453 STEP -i: FOME L-1, FEEKEC Io: Lo & L-11 NEXT 
ga fe INTERRUPT ROUTINE S€459-sE726 TO TOP OF MEMOSY - £y L = LOWER Lt 
‘Tt # LtE2Ss PEM THIS IS THE KEVEQARD-TO-ASCLI-TABLE POINTER IM RAM CRTS? 
cH = KT eesé 2 kL = KT - S58¢rHe: REtt LOW ANO HIGH BYTES OF HEW TAGLE 
“OME L223 PORE 141,234: PORE Le2,255: REM JSR $fFEA TO UPOATE CLOCK 
Rel elas: SHARSP M256; SLHRSR-OSEAaSHiis PORE SR-S,SLHs FOKE SP-4,SKx 
7eM PEEVIGUS LIKE ALTERS A JSR INSTRUCTION TO POINT Ta AUR RAM ROUTINE, 
"RE Ct1 as LA: PORKEL +136 KH 
sa BOTH REFERENCES TO THE REYBURPO TABLE CHANGED Ta POINT To RAM, NOT Ro 
"PINT'ECLRILRYSIENTER de WHEN YOUR KEYBORPQ IS COMPLETE’: PEM COULO BE O 

THES EXIT 5 
PRINT" COOHHIPPESS KE'’y FO BE CHARGED CRVSIGECRYSO] ENTER 
ee AsSlit VALVE, LIKE THiS: Wid"sks sFEM To CISTINGUISH 3 FROM CHRS 

3> 

TF E>" #¢e" THENS OS 
KaRSCCh#> : REH FTF A VALUE HeS BEEN ENTEREQ, NEXT LINE FINDS CORRECT K 
IF LEFTS¢r6,1>2"Y" ANT LEH CK S55 THEN KeVALCMIOSCK £29 
FOR J = 1 TO BO:IF FEEK (S9mGR+ I> ¢> & THEN MEMT: PRINT “CRYSINOT FOLD" 

se Sheps ! S¥3IHOQT FOU" as 
J= JS * KT 3 REM J IS THE POSITION IN THE POM TABLE 3 PRM TABLE MAY YARY F 
FEM WE NOW HAYE POSITION ¢= 39 OF SMWIGHT KEY IN RPELOCRIED TABLE IN REM 
PRINT COOWHMIFFESS KEY TO FEEL ACE CRVSIOPCRYSO] ENTER 
IMNPUT“ITS AGCIY VALUE, LIKE THIS: Vid" sks : 
IF ¢="*64" THEHSGO 
KrASE KS) 
IFLEF TSE, Lacy RHO LEN Ch $o>. THEN RaVALCMIOS KS, 2 >> 
FORE J, sREM PEPLACE THE PREVIOUS KE'’y IN THE RAM TRELE WITH THE HEM GHE 
GTO 96 7 REM Medd GO THE NET CHARACTER 
POM FINAL POUTIME: PORE 2 FOUTIHES Th CHANGE INTERRUPT RB 3 

: M * A x => roe . CORESS 
OTA 120,164,A5,199,144,165, 025,135,145, 96 
ATA 129,165,0%,1393,144,169,279.133,1465,94 
FOR Joe L-20 TO L=-13 FEA ws PORE Fea HET 
Los L~oh: FEM HER COW MEMORY LIMIT = STRHeT OF ENTIFE FOUTIHE 
PRINT ECCPICOOWH ISHS" sla TUES DM THE EW FEY BOAPO, AbD 
PRINT“ SYS" 30410) “PETLEHS TO HUFMAL KEYSER 
Pore Cee, Leas - GTA + eda er see eee PORE L468, CL e¢299/256 
PEM TUPI-ON ROUTEME WILL ROW Lod THE COPRPECT THTEFeURT AOOPETS. 
PEIMTOCCOMHYSEVE FROME TACT 
FRVHT " ee" yn GASB: PRU " TO #" pr Lom Th t GOUBAOIs PRepil 

4" 

Eas 

Rett owl Ot LIME DECIMAL TO HES CONVERTER tet 

NE ee ee ne! Aer eeec henna Tr TRE IT LARA Lema Ta niihe gy 1 
(RETURN , 
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Single-key entry of BASIC keywords éc, Special-purpose programmable keys can be 
implemented on the PET/CBM. The Shift-Stop key of course is a ROM exampl.: of this, 
KR forces dload "*",8 in compressed form into the keyboard buffer. Commodore's VIC 
and the ‘standard data entry’ machine-code routine ulso have programmable keys. The 
following example Dlustrates a method of patching the [KQ vector, after moving it into 
RAM, to add extra keys. It does this by coding the right-shift key as ASCII 7, which 
ig not otherwise used, then checking for (his value when the keyboard is scanned. if 
it is found, a short routine converts the shifted key into a BASIC ward and prints it. 
This version is BASIC 2; I’ve used addresses almost identical to those in ROM purely 
for ease of reference, moving the IRQ routine from E62k to 362E for instance. The 
principles are similar fer any ROM, although i2” screen modeis tend to have longer 
decoding routines to process the automatic repeats. The left shift key operates with 
the shift-lock; for this reason the right shift is preferable as a contro! key. The key- 
board has about 64 alphanumeric and punctuation keys. The routine that follows ex- 
Cludes some of the 75 BASIC 2 tokens, including *,-; ....7,=,< which ave single keys 
already, END, and GO. 

{t) If BASIC in in use, set the top-of-memory to $2000. 

(ii) Move E62F ~ E747 to 362E - 3747. This ix the whole of the interrupt servicing 
routine and the decode table. We can add our extensions to this routine at 3748. 

GH) Poke 36CF and 3696 with 36 in place of E6. [These locations look st the 
ROM decode table; they are both LDA E6F7,%. After the poke they reference tre RAM 
table]. 

(iv) Poke $3702 with 7; this is the right shift key, appearing as the first of two 
teroes in the decode tabie. 

(v) We put @ patch at the point where the shift key is tested. The short piece 
of code following LDA E6F7,X /SNE xx/ processes the shift key, storing | in its flag, 
After our modification, right-shift stores 7 in the flag. 


369F JUMP 3748 :JUMP TO THE FISST RAM ROUTINE AFTER THE DECODE TABLE 


3748 BNE 3751 

374A LDA #Ot 

374C STA 98 

3748 JMP 26B8 ;THESE 3 INSTRUCTIONS IMITATE THE ROM ROUTINE (BUT JMP, SOT BNE) 
3751 CMP #07 =, LOOK FOR RICHT-SHIFT 

3753 BEQ 3758 

3765 IMP 36AT ;IMITATES THE ROM ROUTINE, RE-ENTERING TO COMPARE #Fr 

3758 STA 98 [STORES RIGHT-SHIFT IN SHIFI LOCATION 

37$4 BNE 374E {BRANCH ALWAYS TO EXIT FROM SIIIFT+FOUND PART OF ROUTINE 


The keyboird with [RQ directed to this routine will behave normally, because #7 is 
Processed by # ynift-riyht, and appears similur to #1 from the point of view of shift- 
key procvasing. What is needed now is a further patch, within the voding which ORAS 
bhifted keys with 480, to test for the right-shift. 
(vi) In BASIC 2, E6D2 has the BCC instruction lesting for huss we replace It: 
7 


CMP #20 
360d JSR 27SEC {CALLS JHE SECOND ROUTINE AFTER THE YABLE | 3768 aCC 3788 
3605 NOP 376A SEC MIE 
375C BCS 375") (IF SHIFT PRESSED, CARRY I9 SET a76c CHP #28 
SIGE RTD 37T6E BCC 3772 


375F LER #8 ;TFST Fut #7 IN RIGKT-SHIFT 3770) «ARC FHA 





3761 BCS 3764 3772 TAX 
3763 EOR #80 ;LERT-3HIFT. PUT TN UPPEK-CASE 3772 LDY #FF 
3763 RTS iANG RETURN 3775 DEK 
3766 {RIGHT-SHIET PROCESSING BXGILS, 3776 BRQ J74aD 
‘ a778 OLhY 
At thia point we have dsaated tha right-shift fron the inft, [3778 LDA COu2,¥ 


and enn insert any feutin: whieh wil serve our purpeywen, 


k 377¢) «BEL 377A 
The example testa for reverse wird sursor-contrel characters, 


DITE UMT UTTS 





with ASCH value deus then 32, lesvingg thesa udiehanyad; 37NU ONY 

It earresty far the 9 arifhmetie tokens, already single keys, | 47KL LDA C692,¥ 

and it printy the Ath. bASIC ruserved word, ushig layle a7a¢ tut PN 

Dur pely tukea fram LIs'h, Daa sn Cats 
(vl) Eunaily, set the §#Q veetor to 3626 to drive tha FIKY HAF a7HO 

few routine, Poking $9F (9145) with $36 (254) is convenlent 37RR AKU STE 

fren WASHC, arap se cass 


Tenn a ge ages 
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Reset switches 


There ar three (at least) reset switches usable with the PET/CBM; 
two are hardware, one is software. A reset switch provide an alternative to turning the 
machine off, then on, when a program his ‘crashed’. A crash (i.e. completely unresp- 
onsive machine) is caused by the execution of an infinite loop. 1t will only happen in 
BASIC if the program has peeked, poked. S¥Sed, or USKed, sithough slow machine- 
code routines (notably memory freeing in BASIC<4) may give the appearance of a crash. 
Code like this: G27A LBA #00/ O27C BEQ 0270 or: 0300 JMP 0303,’ 0303 Pr O300 
ovviously gives an infinite loop: so do some pseudo-opcodes ending in 2 when written in 
hexadecimat. Usually, of course, the cause is more subtle than this. Typically, RAM 
code is overwritten accidentally, or a wrong location is jumped to, and the new code 
happens to hyve a loup suinewhere. Incorrect stack handling can easily cause this type 
of problem; so can memory-move routines, 

How do hardware switches work? The earticst, for BASIC 1, made use of the 
reset vector ot (FETC) in all 6502-based sachines, Normally, this vector ts used wher 
the machine Is switched on, and fumps to a routine to initialise the whole of BASIC, 
poking in software values, and incidentally calculating the amount of RAM, and also 
configuring ail the input-output chips so the keyboard and cessettes and so forth 
will operate properly. However, if the so-called ‘diagnostic sense’ pin (bit 7 of PIA 
1) is low, i.e. grounded, an alternative routine is entered, originally a test routine 
for BASIC 1. This feature has been retained in BASIC>L, but the atternative fs now a 
‘call’ entry to the monttor, printing *C in place of the break entry's *8. This is use- 
ful, becnuse this entry retains most of the features of the program in RAM. So this 
switch requires two connections: one fron pin 3 of the user port to ground {see the 
diagram at the end of Chepter 9. Pins 5 and 12 are the relevant ones). And another, 
connected from pin 22 to pir 25 on the J4 connector along the right-hand aide within 
the PET/CBM. This puts the machine into the monitor. ({f the 'disynostic sense’ pin is 
Icft low, switening on causes entry to the monitor, not BASIC. [f it fs disconnected, 
pin 22 to pin 25 will reset the machine inte BASIC, clearing most RAM). Unfortunately 
this process is not hezard-frec, since gecutiding reset is not safe (on the PET/CBM) 
for more than a few secunds. Moreover, the start of the resctling process alters the 
stack pointer irretrievably. The usual provess on entering the moniior ig to enter .X 
to return tu RASIC, then CLR to set the stuck (among other things), Machine-code is 
tidied by entering a meaningless command (usually .; is used) then changing SP to 
*fFPS or (BASIC 1) #FA. 

A safer method (with fewer wires) uses the non-maskable interrupt (NMI) line, 
which has # vector st (FFFA). This was unusable in BASIC 1, but BASIC>1 sets this 
vector to print READY. In this case, pin 24 of J4 is momentarily connevted ta pin 25 
of 34. Either of these methods, to be used routinely, require proper harcware, with 
4 cupuc.lor arrungement to debounce the connection. (Note that these pins are marked 
on the printed circuit borrd),* The NAL method fails with the X2-type crash. 

Software uncrashing relies on the normal interrupt sequence for ita effect. {f the 
Interrupt is off the method cannot work. And it too Enily with X2 crashes. These re- 
strictinns are not very serious. The method is straightforward; we can redefine the 
Slop key uaa reset key by slightly modifying the interrupt processing. 


An interrupt causes the progrum coucter end status register to be Pushed on the 
stack, and the piogram counter to bo loaded with the contents of (FFFK). [n the PET 
A,X, and ¥ are gaved and =» RAM address juopa to EOBG/E82E/E465. Thik ig: JBR update 
clock & load a from E812 (to test Stop), then the remainder of the reutine and RTs to 
return to the puin procaumsag, 

Tf th: RAM atdrown polnta to # routina of this sort; 

SA update clock/loat £812 

CHP #EF 

BKQ oJ 

UWP remsinder vf interrupt prucesming routine 

dR? machine-code wenitor 
then the auftware rede? bs oporatiunal, 

Thin routine leaves three bytes frum the interrupt om the stuck. Naturady a differant 
Version la needed for each type of PEV CUM, BASIC 4 ia alightly different frees the 
*inetructicas for ete lpg hoch typan (almultanonualy') arn printed {e.eo ln Xb-wiero- 
computing, (4 Gtrasmu, Gepe.'#9}, Some other hardware t=fcks of this sort are poseinie 
whth the 8592, KDY (ready) can helt tha 6502 when it 1e# fotching opcudes, wo thet 


alogie bnetructions cag be executed, for exuaple, 


lie AE inal IY aA Sai ER NONE ARTIS ote A ae 
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others; the version here causes the clock to run at 5/6ths normal apeed with i2-inch 
screen CBMs!* 


BASIC. 1 BASIC 2 BASIC 4 
JSR PFEA 20 EA FF JSR FFEA 20 FA FF JSR FEEA 20 EA ¢F 
CUP #EF Cy EF CMP #EF co 2F CMP #EF co &F 
BSE +3 DA O38 BNE +3 DO 03 BNE +3 bo OF 
UMP O40F 4C OF 04 SMP FOIL 4c 11 FU JMP D472 4C Ta Da 
SUP EGSS 4C 82 FG +MP E631 4C 31 £6 JMP £456 aC 58 E4 


EPROMS Unmodified PET/CBMs have 7 sockets for ROMs on their printed circuit 
beards; HASIC<4 uses 4, and HASIC 4 5, so that there are empty suckets spanning 
$5000-SFFF, $A000- $AFEF, and (BASIC<4 only) $B000-SHFFF, The sackets accept eith- 
er 2K or 4K EPROVS, of type 2716 or 2532 respectively. An 'FPROM' ('Erasuble Pro- 
grammable Read-Only Memory'} appears in use like a ROM; it van be read from, but 
not written to, As its name implies, its contents can be erased and replaced: to do 
this, an EFROM Programmer or 'Burner' has the required bytes loaded into it, ond 
these are entered in a sesti-permanent way into the EPROM with a relatively high voft- 
age pulse of 27 volts or so. Erasure is perfurmed by removing: the op#que covering on 
top of the chip and exposing the chip to UV tight from what has been enlied "the 
world's most expensive ultra-violet lanp', One of the first PET chips was Nestar > 
'Toalkit'; it was also one of the most popular. It added commands to BASIC using 4 
wedge. These are rather rudimentary truce, step and renumber facilities, tape append, 
‘find’, and variable dump. Later BASIC extenders included 'Disk-o-Fru' for BASIC z, 
which adds the disk cominands found in BASIC 4, and 'Command-O' for BASIC 4, with 
screen and directory scrolling up and down, a 'print using’, and search-and- replace. 
‘Power’ is another well-known EPKOM, but there are many mora, including some 
complete packuyes (Visiealc, word processocs). Most are designed for the $9000-SOrFE 
slot, with $AQ(0-$AFFF a ciose second. Obviously it is impossible to run EPROSIs which 
confiict in their requirements simulianeously. Some have alternative versions for several 
slots; few Lf any will relocate. Multiple sockets ave available which accept several chips 
and allaw switching between them, aud this may be convenient (if expensive). Amongst 
the several dozen chips on sale are some of the 'Tooikit’ utility type, intended to help 
with writing BASIC, and some providing similar hetp with muchine-code. Others re 
@esigned for business use, casing input and output for example, for graphics use, — 
some in association with hardware, and for tape or disk use. Some few are specific in 
Rature, dealing (say) wlth matrix calculations, Unfortunately, documentation is often 
poor, and reviews ure usually rush jobs whieh fail to mention bugs and pitfalls. The 
Purchaser of EPROMs thercfore should be wary. Moreover, as the technolugy to copy 
chips becomes more widely available, some of the incentive to pruduce pfuod-quauty 
firmware is lost ur at least weakened. : 
Other types of EPROM - EAROM = Electrleally Alteruble KOM, for instance - are 
only important when hardware modifications allow the CBM to write to ‘ROM', 80 that 
toftware can be huld semi-permanently, in ‘Instant ROM’ and other products, Thia re- 
guires the write-enable line and a power supply connecter to the 'KOM’ packaye, 


Other Black Boxes More ambitious add-ons Inciude CP/M, a well-kaown ateudard 
microcomputer control program, designed for the Z8¢, The CAM hag an external #30, 
which runs the program li place of its 8502, Thia is a radical difference. At the tina 
of writing, the U.K. company ‘Small Systems Enginecring’ appoars to have the only 
Working version. Prestel (Videotux In the US) iy often dumonatrated on micros, and 
®t Jeadt ono »ystem In evaiiable. At present ails is (virtually) @ receive-only syatem, 
but 2 way teonamlyston may be feasible - Mullard’s ‘Lucy’ chip ln reported tu Le able 
to handle this al apeed. Some multiple PET<to-disk sayrtems exist, enabling users to 
Shace the use of tha relatively expeosive diska. 

Industry, process control, and research = Industeiai applications of BET type mise 
canputers range Crom dedicated Ce. ainglo} operation as an electronic tnstrument, to 
“This can be Prog raamea around vy luadiug the accumulator from EXIA indepondentiy of 
the clock upifate routine; LOA Kelas CMP EGla/ BAR -B/ CMP #EF/ BRE o3/ JMP MONTTOR/ 
JP ERQ RERVICE. The £E*}2 proceaning provider @ simple dybounce, 


er < = . 
ca p ee ee be ee Le ery 
i ea A ee eet Ee kt ee te ee = het acead 


lace Rat I i inal Reelin i al a I a A el oe ar a i el I a de eel 
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fuirly large-suale process control, Full explanation of the hardware side of this is out- 
side the scope of thia book.* But a fow examples iNustrate what can be achieved with 
the aid of these machines. Most such applications are developed in industrial or acad- 
enic laboratories, with some interchange of ideas between the two. Eurly examples in- 
clude stepper moter control, one of the ensier devices to program, and measuring and 
Inspection machinery, ‘such as balances and fauges. Daia loggers, taking edvantage of 
the video display, include equipment like transient recorders and spectrum analysers. 

Control equipttent has been developed to handle the more mechanical side of research 


inte uniinal behaviour, Smaller-scule models of test rigs have been constructed: a much- 


publicised motor-eugine tester and s computer-controtled driil, again are typical of the 
sort of thing. There is « well-known stancatd computer application of mathematics! 
theory (to cutting up sheets of metal, paper, ete.,which is the sort of optimisation pro- 
cess capnble of calculation by the microcomputer. Recently, the computer press carried 
a story of a CBM equipped with hardware (via the user port) and software which were 
able between then to contro) a dniry packaging system» The engineering side of the 
packaging machinery was controlicd by pneumatic valves, 

Successful hardware of any degree of complexity requires considerable skill in 
design, partly because of the difficulties in esthaating overall volerances and cumulat- 
ive errors in all the parts when they are put together. As for the software, I quote 
the Chairman of Research Machines Ltd: “It is virtually impossinle to overstate the time 
tuken to get software up and running ... a successful application within one year 
Means you're doing well at the mument...". 

Single on-off switches are easy to implement with machines like the PET; all 
that's needed is @ set-up which protects the PET from excessive current or voltage 
while amplifying its signals. Chips which demultiplex (e.g. 3 wire to 8 wire convert- 
ors) are commonplace. Anuloguc-to-digital conversions and vice-versa ore more diffic- 
ult, becuuse more lines are used up: so (say) temperature contro! is harder work, un- 
less simple on-off controls are sufficient. Such devices may have to be polled (i.e. 
exemined in turn), of controlled by regular timing, or perhaps use an interrupt, In 
addition, data conversion may be areded by or from pieces of equipment with non-PET 
data conventions, Of course, an off-the-shelf package of combined hardware and soft- 
ware, if it exists, may be able to deat with all these matters satisfactorily. 

The program reads and diaplays the 
input from an analogue: tu-digital converter. 
This one (a Siliconix LD130) converts valt- 
ages from 0-1 into binary eoded deeimal 
output, one digit at a time, so the hundreds, 
tens, and units figures are output individually. 
The result is .000 to .999. Bit 7, when set 
low, signals correct data in the byte; bits 4, 
5, or 6 signal units, tens, or hurdretls, de- 


TARLE #40 #20 #)0;TEST H,T, OR U 
START LDA E84P ; AWAIT END OF 
BPL START ;¥ALID PULSE 
LDX #00 
WAITY, LDA ES4F 
BMI WAIT ;AWAIT VALID DATA 
COMP BIT TABLE,X;1008? [1087 1873} 
BEQ NEXT ; IF NOT, BAANCH 


pending on which one is high; and bitsy 0-4 roe #50 
hold the current value, 0-9, of units, tens, F 
hundreds. Hardware programming differs me si Oey ee 
from ordinury PET/CHM program in that the NEXT INX ' 
Ede i ike RAS . ay 
addresses which lock tike RAM in fact vary CPX #03 SALL 3 DIGITS? 


according to externul events, so the style of 
programming has to reflect this. The compar- 
atively long-winded programs which reault 
are typified by this apecimen. 


BNE COMP ; BRANCH IF NOT YET 
BEQ PALT¥ 


** small number of books deal with CWM-related hardware, The moat recent is "RET Inter- 
facing’ by J Downey and 8 Royors; this is no. an introductory text. ‘Programming and 
Interfacing the 6502‘ (M DeJong) deals with the GS02, not apecifiecaliy: the PET/CBM, in 
some detall. Both theme titles are Listed ow 'Blackburg Serleat putiications in the 
US. Gf earlier booke, Caaton Fostur's ‘Programming @ Mierecomputec: 6502" ta all about 
hardwars, but sowtiy the KIM-1; and Zahn’ ‘650% Applications Book’ has Rothing apecific 
en the PET SCR. 

Tie computing press haw hordenare acticlas; often, rather wuryprlaingty, hardware 
io covered more celiably by Journals of the Wiroluan World end Fraction! Electronica 
type, whore, presumably, the roadermhip ant oditoclal mtaff expect a reascnable @etand- 
ard of accuracy, foumtigow outsides contrihutore have a sistiar affect; fer axvaepla 
CPUCK 3 #3 haa an artici# op paraiis! to sariel corverssun by A Strutt & K ionba of 
Cf which ia unusually well thought-out. 


SENET 62 perc re galt terete aerial Fe PI, SRE RE Np ORE EIT tO I Ney ete ony casters amen aT 
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CHAPTER 9: GRAPHICS AND SOUND 








9.1 PET/CBM Screens 





i machines to date have had @ screen 
Screen and character-generating ROM Al! CBM mach Mae arcetce Chis! Oe 


i i ilt in. Commodore's VIC (‘Vi : a 
(or VDU = SN ee eae ayia ietociaaie pun) departs from thi» nna: 
Hew eres ‘6 and Tandy, an external TV, so that colour is available. gen aaae 
ek tek ora inch sercens, always bluck and white; Paci computer denons 
ed by Commodore at a show hasn't subsequently ponUr et “ Facet tieeat Suni genite 
Confining ourselves to current models. we can see aise a oe ee rad 
phosphor 8 inch screens were replaced by 6 inch green ae ONS, fine Poa 
laced by 12 inch green screens, presumably to cut down on manu ee eee ok 
All new modelo whether 40 or 89 column, now have 12 rh et cian yee 
time, probably the40-column modcls will be discontinued in favour ¢ degen atau po! 
(This ie a guess on my part). The internal bead hans been tidied an 
i ¢ : em is uli minodere. : 
Dee al cea. le ake. Rasher ee ee extecnal monitor} has vue papel 
horizontal paaltboiis vertical position, and indication whee Lang re Meine ig the 
screen. Each character is made up of # dots by 8) typically se ema iets Me intoe: 
actual aren holding the points of the character, 50 the edges “ Ebates canttals 
fere too much with their neighbours. Nevertheless the kets erie peat oe 
can be improved by printing CHR$(100)s above them; and eau Se aly A 
the facility to change line separation using Saino aan sae ee eea camaeier. 1c 
fics iaeee are 68 Sane Be oetna meeeth before flyback to the start. As 


: »p, there are 8*25 = zs Dat i ae 
eri ee the flytack is handled differently by the newer machines, muking 


i soatibilities with the older models. et 
ei aaiginal tankers can be cornmected to PET/CBMs to enable (say) a class to wa 


; rich provides 

a demonstration program; the hurdware is connected to ne User Uo heiwactively. ee 
oc ver ethe ene ged teAle Te ee led foc crea diagrams (neither of which 

N, joint issuc 1 and 2 or the reir ; 
es These produce output svituble for monitors, not ae ee nahane tate 

The actual pattecn of dots making up 4 character eM naar the other ROMs. It 
generating ROM,*which is in the main bourd of the PET HC a ® look-up: tnuia, 256 
converts any byte into a fixed pattern, in 4 manner ean ft switch between several 
separate patterns are stored within it, although it is posse oars available. POKEINg 
ROMs, and Commodore has its well-known pair of Han acid Msn r eases graphics 
59468 with 12 or 14 switches the character generator inte Wher ee it srnikuey Gee 
mode or its lower/ upper case mode. The charucter sety are Hi i sles the Ge ease 
cept far the fnct that A-Z when shifted produces graphics ae emailing euraceera 
and aluhabetic checneters in the other. Must (all but Hgeiaueg S unsaa th aerate: 
are unaffected by the ROM poke; the chart on the following ag oer ihe cra aotol 
ment. If PRINT statements are being used. it Is impossible . erlment will prove. 
graphics end lowers and upper-case, a4 the chart shows, and expe 








but | = v ian haa 
*Commodore's ¥(C uses anuloguus, but different, Pagel da are nage Poona ape re 
22 by 25 characters, fieting allgnhtly leas than 2 pagca © pear shaa ti gaan Paley He 
Character generation is a RAM function, #0 user-definahle 7h ee titer ama a-apee 
(it Jaburioun) te write, Zach cheroctor’a colour is Se ccdce Sato pon any 
in a S06-byt# Lable, Gnty one background cotour A ee 
NEXT PAGE: Table of CBM 'ASCIU’ characters, In decimal / hex order :- 


HT o¢ i int the daltie symbol. 

UNT "S$" A PRINT CHRSCIG) print the dal sathacata gs 
ane cae) prints ‘a’ ar 'A' depending on tho nero A - sie aeons 
PRINT CURECED) aoe PRINT "THOME)" Ge. PRINT ET) these re 7 
5 7 yu 
Hapeeters ar oavallabla only on the O32 ard We Ineh dust. 


penta of characters 32-09 aid 160: 19. 
the quotes May ia net ser, There 


Exusnile: 


"Then cantral ¢ areas cae 
Note that 9 bet ane 224 25a appene as 

lt ke however, 
Se PRINT CURSCOR) prints a quate mar; : es 
pee aa a cdinety shorioters and 64 yraphices/ upper case ehiurseters $n wll 


VHAGE anty. 


: ” poe ae a en a“ Ne <a eee te 
one c = aps 8 TR ET 
TER ete aoa wp ater yma mem eH EM ek RC Nea ST “Lem RTO ETS SEE SPE 


acti eRe 
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1 01 6541 a A 129 al 193 CL A él The earliest PETs followed other computers in giving capital tetters primacy, so 
2 02 6642 b B 4130 82 194 C2 8 7} the shift key moves from upper case to lower case, CBM machines adopted the normal 
3.03 STOP 67 43 ¢ C 131 83 [DJLOAD& RUN 11965 C3 C 3 typing convention of shifting to upper-case. Their character-generating ROMs are 

4 04 64 44 d D 132 84 196 C4 O r= consequently different, so that the chart on the previous page has its two scts of 

5 05 69 45 e E (33 85 197 C5 E a alphabetics arranged with 65-90 as upper case only, and 193 - 223 as lower-case or 

6 06 7046 f F 134 86 198 CS FO graphics. This jeads te a confusion of terminology. We can talk about ‘lower-case mode! 
707 BELL* WM 47 g G 4195 87 199 C7 CG A and ‘graphics mode’ with snything except BASIC L; ‘standard’ and ‘siternate’ character 
& 08 72 468 Wh H 136 88 200 c8 A [TJ sets are often used to describe this eurliest arrangement, where ‘standard’ means that 
909 TAB* 7349 i | 137 8S SET TAB* 201 69 | &) shift gives lower-case, and ‘alternaty' shifts to graphics. I shall use ‘graphics mode 
10 0A LINE FEED i4 4A j J 138 BA 202 cA 2 [YU e (POKE $9468,12) and ‘iower-cuse mode! (POKE 59468,14), hoping that business key- 

11 OB i$ 4B k OK 139 Bb 203 cB K FY} board uscrs, with graphics obtainable only by poking, will uaderstund! 

12 0¢ 7m 4c i ob 140 8c 204 cok A couple of simple programs show how the screen memory and the character-gen- 
13 OD RETURN 17 4D m M 14L BD SHIFT-RETURN [295 CU M 8 eration interact. PET/CBM sereens are wired so that consecutive RAM locations store 
14 OF TEXT* 78 4E nN 142 8E GRAPHIC*® 2068 CE N C4 the charactera in the screen in the normal left-to-right then down sequence. The 

15 OF SET TOP! 794F o O ‘1149 8F SET BOTTOM? 207 cF o [ starting location is $8000, exactly midway in the 6502's memory map. 40 colunin mach- 
16 10 gu 50 p P lad % goa pa Pp ines store 49°25 (1000), and 80 column machines 90025 (2000) bytes in this way. The 
17 11 CURSOR DOWN 81 51 g Q 145 51 CURSOR UP 209 D1 Q [e] } address decoding is incomplete, so PEEKs and POKEs to locations outside the expected 
18.12 REVERSE 8252 rf R 146 92 EVERSE OFF 210 D2R Cl range produce echoes or ‘images’ in the screen. The 40 column mactine uses 1000 of 
1% i Aer are 8153 s S$ 147 93 CLEAR SCREEN 21103 5 (4 : 1024 bytes, $8000 - $43R7, to map the sereen. (This is 32762 - 33767). The 24 bytes 

v4 ELETE CHR.) 84 54 t T 148 94 INSER HR. + from $8368 - $83FF are normally unused. 

QL 15 DELETE LINE'] 85 55 u VU 149 95 eres nee | ra fi 5 In a 40-column machines 46400 behaves just like $8000. An $0-column machine, of 
2216 ERASE END* | 66 55 v V 130 96 ERASE START* [214 D6 v & course, maps its screen to $8000- $8809. Since the starting address ($6000 = 32768) is 
23°17 87 57 w W FLS1 97 215 D7 Ww fal identical in each machine, * the following simple program displays all 256 characters 

ce 4 8868 x X f152 2 216 Ds xX BA which the ROM can generate: 

ai 4 SCROLL UP as - y : aH op SCROLL OOWN* ~ py ¥ C1 10 FOR J = 32768 TO 32768 + 255 :REM 256 VALUES NEED 256 SCREEN LOCATIONS 

27 1B ESCAPE 91 5B [ 155 9B a ae cq s 20 POKE J,K: K5a+t :REM POKE 0,1,2,3,...,255 

28 1 92 5C \ 156 9C 220 DC &} aici 

29 1D CURSOR RIGHT | 93 5D J i57 9D CURSOR LEFT 221 DD ri This fills the top few Hnes of the screen with an entire character-set. We can look at 
1 94 5E + 158 9E 222 pe EY Gr both character sets by adding this line to switch between the two: 

Pr a SPACE ld a SPACE: is i euieT SPACE af a SJ i F : 40 POKE 50468, 12: POR J = 1 TO 500: NEXT: POKE $9468,14: FOR Je1TOS0O: NEXT: COTO4O 
33 21 4 $7 61 ! 16. Al E] 225 EL REPEATS This displays pl! the characters which can be generated, since no other valucs than 0 
34 22 QUOTE ” 98 62 " 162 A2 [gy 296 E2 to 255 can be stored in the sercen RAM, and only two modes exist, It may surprise 
3523 4 9963 @ 163 A3 (7 227 £3 business keyboard users to see all these graphics, which cannot be entered from the 
26 24 100 64 $ f64 aa 228 BA keybonrd: the decoding process of the keyboard is rewritten (e.g. in the $032} to 
735% 16k GS & 165 AS . 229 ES remove these character Chapter 13 gives a machitie-cede routine to enable any char- 
38°26 ¢& 102 66 & 166 AG Ea 210 EG acter to be input from the keybonrd. A table of CHM sereen memory, showing decimal 
39 27 = ws 67 ' 167 AT CJ 231 E7 and hex values corresponding lo yraphics poked / penked to the screen, on the next 

49 28 ( 104 68 [ 168 AS ka 232 EB page shows the entire gamut of characters for BASIC>L. Where lowercase mode and 
4i 29) 194 69 } 169 AD kOe 237 ED graphics mode differ. the two alternative appearances are placed side by side. It is 
42 2A * 106 GA * 176 AA [} 234 EA impossible for the pi symbol and the 4 by 4 chequered symbol to appuar on thu same 
“ ae + 107 6B + 71 ag [B 235 EB sereen, or for lower-case x and the heart symbol to co exist: limitations like these 

, 108 6C - 172 AC ‘ should be borne in mind. 

45 2U - 109 6D - 73 AD +a ne ap By careful synchronization, It is possible ta watch churocters changing modes. in 
46 26. 106 - 174 AE G.) 238 EE fact, with machine-code, the sercen can be made to dispiny non-existent characters, 
47 WF} li 6F / 175 AF CJ 239 EF made up of slngle tines from several differcnt characters! However, the severe tine 
i 7 a 112.70 0 176 BO tA 210 £0 requirements make this technique hard to vse, This BASIC program® 

50 32 a i : Pa ne iv rans te 10 FOR J = 1 TO 1000; PHINT "A"; : NEKT: WEK 1.£. SHIFT-A. USE 2000 FoR &80-COLS. 
513304 11573 3 179 BA 5 243 F3 20 Xs5utae: Yet2: Za14 : AEM RCH LOCATION AND ITS POKES 

S234 4 116 74 4 140 B4 {i 244 4 JO POKEX ,¥: POKEZ,Z:GOTOIO : REM RAPID SWITCH BETWEEN HQVES 

pe 3 5 i775 $ 141 BS ED 245 FS first Filta the acreen with « charseter which changes wher the mode alters; [ve puta 
ise 36 6 tis 76 6 iz GCF 24h FR shifted letier to enaur. That the program will work with BASIC L! Line 10 inkes about 
a sh i Fete is; i 181 47 ie 247 FT télzbth of a second to « ute: BASIC 4 machines find this too fast, so slow Tine 30, 
sane! laisse PY 24 Fe CP ee ce haf Secs igs ten enate what at ike Geta aactn Misia gee fore eS Ages _ 
5s se 3 vat 799 THS bo bad 2449 FS WIC agein ia Mitferent: although the screan ie memory-eapped to RAM, the actual lor- 
ed . : Be a : 146 BA 44 CJ ub) FA atton can very, dependisa on the anqunt of RAM Inatalled, 
Gh ae } 124 1 > re ie Ma ah ty Poe hk Cotevels, in SUPA of March 19A1, writes that people with cartain furay of epil- 
Li ae es 125 7D = is9 HD fi a, FC rosy Ceo. temporal late mpilapay) may have an atiack Snducad by the pragrem, 
fe dk ¢ t2h TE ¢ 14 BE ‘a oo rp ‘Creative Cepputing Crel.6, #0, dated Oct. '7H) has aome Infarmakton on videw 
63 0F 7 127 7F 19 RY : beh rie GQispleyn. Thin journei spechuliues in, ve at Jeast de biased towarda, artictew on 
os JF? Lae: aaa FF F gtaphica, gasere, and suuad. 
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11 OB K°K(49 2R + [75 JB K 21107 5B fe [139 Stara) i7LAB EQ] 203 CBM 

1 oC LP 2) 476 4C LAG 108 6C Taf t40 HC gee 132 AC FAL 20 CCaM: 

13 OD mM}45 2D - 177 49 Mb] 109 GN EO fF 14t 8Pestigs3a AD ft; 205 CDRS 

14 OE n N/46 2E WW Ws NOY1LO GE By f 142 SEMIS, is4 AL 206 CEM) 23 + | 

15 OF 9 O47 2F 7 179 aF OF] 111 GF Go [143 Br BSH] 185 AF Pal 207 CF Sie) 239 EE 

16 10 p Pla 300] 80 BN PL Li2 70 Cy F144 99 ag] 146° BO” A] 20s DO Tas] 210 Fe 

17-11 q@ Qh49 BL 1 Bt Sk Qt] Ld 7) Ey | 145 91 GMP 87 B1 py] 203 Di bic 2a. Fl be 

18 12 r RISO 32 2 482 $62 RC] 114 72 Ey f 148 O2PE Ry ks BZ FAL 210 p2qieleq2 F2 om 

19 13 5 S{5t 333 383 Sd Soy (15 73 BD 14T 94 FEE 129 BS pep elt D3 cla) 43 FS Be 

20.142 Th3F 94 fea sd Try iis 74 pi fide oapteAp 19 Ba Glp2r2 Da wet 244 Fa 

2115 u UlS3 35° 6 485 $5 UG 117 75 yt | 149 YOM ist BS E213 VSwe) 245 FS Oe 

22 16 v ViS4 36 6 186 56 VIX) 113 75 214 DEWEY 46 FG B} 

23:17 wW155 277 48757 Weal lig 77 & 215 DTM) 237 FF 

2418 x X[56 58 8 [bb Ob X ‘aj 120 73 ‘216 DS gey) 243 Fs 

2 19 y Yi57 4Y 9 [Bu 59 YN zk 79) | 153 99 Fay] 195 BO B), Zi? DoyaMi) 249 FO Pe 

26 1A 7 2458 QA: 190 SA Zl e2 TAGGLY 154 GARE 15h BA Bp 218 DAT 250 FA MK 

27 1B { 159 3B + [91 SAG | 123 7H a [155 98 ga [197 BB FA 2to OB 23 | 

Wi LOIS Se SCE 12a tc ee 156 90 ye [58 BC fal e20 DC TH 
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reversed as 


PET /CBM SCREEN MEMORY 


for example with redundant spaces, to abaut 1/l00th second, When the prograni runs, 
the screen fills with repeuts of a character ~ this tedious purt can be speeded up in 
various ways, e.g. by printing fewer, langer strings - then enters an infinite loop. A 
band, corresponding to the times when the churacter set is chunged by a poke from 
Ilne 30, but is not yet changed back, appears on the sereen. Close examination of 
Individual characters shows they are partly mady up from ehift-A, and partly from the 
spade graphica churncter. {[ em referring tu those characters which form the bound- 
ery of the bands). How dong this happen? Line 46 runs in synchronization with the 
sereen refresh. That is, every 60 timey per seeond, Gr $9 with the 9043, the screen 
finishes scanning (the scen reaches the bottom) and on interrupt bs gunerated, the 
identical interrupt to that which drives the keybhoerd input processing. Aftur a ahort 
period of Mybnck, the sereen is refreshed, scennlng sgauin Crom top to bettun, Our 
BASIC program changes the mode exactly twier during one complete scan, so the screen 
is separated Into bands. [f the Unmlny of BASIC slows vlighUy, the bands wil start to 
roll up, and vice versa. (Try preaslng a key}. The atelogous process in muchlne-cade 
works on the fullowing Ilnes: there ere 825° Wd lites of dota, all of whlelo wre sean 
ned In (say) P/Sth accond. Therefece one row of dots tnkes nbout 1/1000 th second 
to lie refreshed on the acreen. This loterval aliows 140 clock pubies te oceur, 8a a 
machine-code routine ean replica sone of the eharuetera Onol Wi 40 or #913) bofore Ihe 
next Une of deta is neraned. Ther prowess must be repented with enchsscereen rafrent 
to give a stath: lage, 

Alternative character: generstlng ROW: to those supnlied ean be made in KPROS 
form fnirty cheaply, wlthcugh In practice there doce tut acem to ty much demand for 
them, The entire ‘graphics mode’ aet can he changed, so tint POKE 99454, 702 maken 
{hy alturnativen (og. Prestet) available, white retiinigy ‘lower case inode’ Tar ude 


- 
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when the system is londing and running normal programs. 


PRINT, POKE snd PEEK The double usiges of the serecn memory and ASCH can be 
very confusing. Tt nay be some consolation ty Tecall that Commadare themselves seect 
to have been confused when designing the software for their printers. Let's start with 
the sereen memory. We've seon that POKE puts a character on the scren, and that 
each poke correspuiids to a character. Iu fact, there is nm one-to-one relation, with the 
sole exception of space (CHR$(I2)) and shift-space (CHR$(160)) which look alike but 
PEEK differently. There is no ambiguity avout the screen: provided we know which 
mode it is set to, and provided we're not worried about shifted or unshifted spaces, 
the character's appearance tells us the value we shall peek from its RAM lovation. This 
diagram shows the relitionship betwoen the keys pressed and the screen: 


BIT 7 BIT 6 BITS 5,4,3,2,1,0 
4=REVEHSED 1=SHiFTED REPRESENT ANY CHARACTER 
Q=UNHEVERSED O=UNSHIFTED FROM 0-63 IN SCREEN RAM 


Because of this, bit 7 simply needs to be feversed to switch a character from reversed 
to unreverced and back. For example, EOR #$86 has this effect in CBM graphics. Not 
all computers use this system. Apple high resolution graphics use EOR #$FF, since 
every bit has to be reversed. Bit 6 selects either the unshifted or shifted part of the 
character set. In this case, FOR #$40 shifts and unshifts a character alternately. The 
remaining bits offer 28-64 combinations, which are roughly divided into the alphabetic, 
numeric and punctuation symbols, and graphics, There is 8 meximum of 64 graphics; 
but reversing each of these extends the sct, and in fact is the only way to complete 
some of the graphics subsets, ag we shall sre. 

PRINTing has to convert ASCII characters into the screen form, True ASCII 
reserves the first 32 characters for control information, and PET took this idea over, 
although many PET screen editing functions bear little relation to any ASCII function. 
So, because of the wreen memory urrangemunt, PRINT CtiRS(65) or PRINT Pa” has 
to poke 1 inte the screen. To do this it simply drops the 6th bit from the ASCII 
value, ofter testing whether the character to be printed might be a controt character. 
This is the reason for the repeats in the table of CBM ‘ASCII’ characters, two piges 
before this. Note that a reversed character cannot simply be printed; it must be pre- 
ceded by the [HVS] key, or, what amounts to the same thing, the reverse flag must 
be set, $9F ($02UE in BASIC 1) holding a non-zero vatue. This can be irritating when 
a graphics set is saved from the serecn as strings; one of the munuals domonstrates 
graphics with a rocket which is drawn on the screen, then saved as BASIC by homing 
the cursor and typing 10" [return], 20" [return}, and 6a on. What they don't say is 
that reversed characters, which are often necessary for a full effect, can't be saved 
in this way in a string. Instead the string must be punctuated with [RVS) and 
{RVSOFF) symbols. 

How does PRINT work? Chapter 5 has information on this; we need consider only 
output to the sereen, Typically this involves the kernel routine $FFD2, 'CUTPUT A 
CHARACTER‘. This first checks for the device number; when 3 (i.c. screen) is found, 
the current A,X, and ¥ valucy are saved, and a set of ruutines entered, depending 
on whether the shift key way pressed, and so on. Control characters are tested by 
routines which are, in wide-serven CUMs, remarkably tortuous. Ordinary characters 
go by a different route te subroutines which put the correct byte into the screen (at 
last!) and update the screen cursor postions and so on, before recovering A,X. and ¥ 
and retucning. It is mot surprising that poking the server direet in machine-code is 
the festant way to tratafer data to the screen. For this reason, all games end graph- 
les programs, and routines which perform functions like reversing the sereen or star: 
Ing sercens in RAM, dtrectly lord and sive the KAM vaturs in tachine code ising, 
foud aceumuliter « store aceumulator style operations. So why use the rouline to print 
at nll? The answer is: it is genvenient. All lie seceed sevoliing, catculation of nuw 
nes, curser aomingg ane movement, is easidy dune, Poke requires both machine-cuce 
and seren-pedtion estculations, BASEC POREIng is not efficent. 

Jie portiot of PRINT winch pute a byte into tha weress differs betweer a& inch 
Keren PET R/CEMS and their liter counterparia, The diferende bo in hardware, and it 
la reflected a the software. Thin ruutines (ETAC in BASIC 1, EGA in BASIC! 2, Béns 
in BASIC 4) ape of lea types; one waits until bit $ of SERIO tx zero before atoriay the 
Keeumulatar’s contents In the acreoen. The other, maro reeent, (ype doesn't writ, bout 
wapn tite charactecs baat full speed. (1 quote Jim Butterfield}, fn the Grat enve. the 
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object of the delay is to wait for the ‘retrace interrupt’ to be signalled, which meang 
that flyback is taking place. [In the earliest PETs the screen was blanked during this 
interval, and new chtracters written inte the screen memory. When refresh took place, 
the new claractevs appeared. Direct poking caused ‘snow’, because the character gen- 
ecutor couldn't tell whether some dots were supposed to be black or white, Hence this 
type of thing: 


TAY SAVE BYTE ... 

LDA E840 ;AWALT RETRACE INTERRUPT... 

AND #20 

BNE -? 

TYA sAKD RESTORE BYTE FOR SCREEN PORE. 


BASIC 2 has this same formula in it; HASIC 4 has dropped it, at feast in the 12 inch 
versions. A hardware rearrangement made it unnecessary. Because of this, BASIC 4 
In the very earliest FETs will give a ‘snowstorm’ effect (well, it's not really that bad). 

With PRINT, a fair amount ef time is wested if retrace has to be watted for, 
because only a very sinall proportion of the scan's time is tiken up with the interrupt. 
In fact, only a tiny number of bytes, perhaps ten, cun be fitted into each of these 
flybacks. ‘The fast-screen PORKTs, discovered several years ago, and then recalled from 
some software when their harmful effects on certain machines becume known, work by 
causing this delay not to happen. POKE 59458,62 speeds up screen writing by a factor 
of abaut 6, in BASIC 1 and BASIC 2 machines. This improves the appearance so much 
that it is pretty weli compulsory with BASIC. Unfertunately, the hurdware modification 
which helped take the 3032 inte the $032, and which made this type of poke redundant, 
is affected by the poke, so that software including the poke should not be transferred 
to BASIC 4 mochines. The dumage is not immediate; the sereen picture collapses or 
diminishes, and eventually a curl of smoke comes from the machine ...(I quote Jim 
Butterfield again), 


9.2 The CRT Controiler chip 12 inch screen CBMs, but not 8 inch, contain a 6845 


CRT (esthede ruy tube) controller chip. Motorola's MC6845 is designed for raster-scan 
displays and can be configured for ‘alinost nny’ screen density; notably 89 by 25. It 
includes facilities for cursor control und light pen opuration, not used by CBM. The 
manufacturer's data sheets arc informative and inctude examples of parameter calcul- 
ations used when initialising the chip. Confining ourselves to Commodore's implement- 
ation, we find the two RAM locations, wired to the address register and the register 
file, at SE980 and $F881 respectively. The first of these is an ‘indirect’ or ‘pointer’ 
register: its contents may be 0-17 (it has $ bits only) and, depending on the value, 
the corresponding register, 0-17 is accessed, and # new paramcter amy be put in it. 
To see how this works, we find that a jump table in the CHM controls the CRTC. On 
awitching on, the CRTC ts initidised by a jump tu $£018. This puts the machine into 
lower-cuse mode and seprrates the individual Unes of text. The same effect is obtained 
by PRINT CHRS$(E4), ‘Set text’, or of coursa by SYS 57368 or JSR $018 from BASIC 
or machine~code, Graphics mode is initialised by e¢ neighbouring juinp, SEI, whieh 
can be performed by PRINT CHR$(142), ‘Set graphic made’, or by SYS 47371, or by 
JSR $S01n.* A further Jump table entry, SEQIE, should be loaded before tt is called 
with eppropriate values for A,X, aad Y; it iy & user-definable entry point. 

Wher any of these three routines arrives at $2988, A and X are assumed to 
polnt to ROM or RAM, X being the high byte and A the low. The Y-regixter hulda 12 
or 14 declmul; thia is poked Inte Uke location te control upper/lower case and yraphies. 
Then 18 bytes, from the address pointed to up, sre poked into the register fiic; this 
menns thet the addresq register is atternalely poked with the register number, On the 
next pare ty a Usting of a whort BASIC program whien exactly simuintes the wetion of 
this. The order, from 17 to 6, micics that of the aischine code, ead the table of 19 
bytes le identical to that for jower-care muda. Running the program therefere has no 
effect whea in norml lower case node. However, Jf the serecn is set te graphies mode, 
ar lower-case mole wilh tne Wes next ta each other ¢e.g. PRINT CUR$C142): POKE 
$3468.14), the progruu wll) take the sereen revert ta tha awiteh-on fppeiranea, The 
DATA values for graphics mode are: 0,0,0.0.6,16,0,0,7,0,37, 25,0, 49,15. 43,4049, 


“These eddroases rolstc ta tug 8032; wt ihe tine of writing t haven't daflnita evidance 
on 12 inch 4034m, In wny come At‘r not hard to find the relevent code; for nnanple, 
the reset vector can be folioned until «@ reference ta incationa BakO & EMAL $4 found, 
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SRT CONTROLLER PROGRAM IN BASIC (80 COLUMN CBM) 


100 FOR J = 17 TO O STEP -4 

110 POKE $9320, 

120 READ Xs FOKE S9oS1+X 

130 NEXT 

200 BATA 01 0r 01010015. 0s Os Fr Qs B24 25297 G90 15s $l 400 4? 

7i0 REM PUT EACH DATA ITEM ON ITS OWN LINE FOR EASIER EDITING 


There is fittle difference in setting for euch mode. (These values are from tables at 
E724 -F73B and E7T3C - E14D for lower-case and graphics modes rvspectively). We can 
now, using this table of registers as a guide, investigate the chip further. Note that 
some combinations of inputs produce odd effects with the CRT; I've been totd that it's 
unlikely that damage could result, but nevertheless the high-voltage equipment which 
operates the tube can emit noises of the sort you'd rather hear on other pecples 
Bachines. 




















REGISTER #! REGISTER FILE DESCRIPTION | CBM LOWER CASE/ UPPER CASE VALUES REGISTER BITS 













9 HORIZONTAL TOTAL 49 ($31) 0-7 
1 HORIZONTAL DISPLAYED 40 ($28) Q-7 
2 HORIZONTAL SYNC POSITION 41 ($29) 0-7 
a HORTZON SVL SYNC MIVTH 15 ($0F) 9-3 
4 VERTICAL TOTAL 49 ($31) , 0-6 
5 VERTICA!, TOTAL ADJUST ® (300) | a-4 
6 VERTICAL DISPLAYED 25 ($19) 0-6 
T VERTICAL SYNC POSITION 37 ($25) o-€ 
& INTERLACE MODE ° Qa ($00) | O-2 
° MAKIWUM SCAN LINE ADDRESS 9 ($09) 7 ($97) t 0-4 
10 CURSOR START @ ($00) 0 ($00) 0-4 
CURSOR END a (300) Oo ($00) 0-4 
STAAT ADURESA (41GH} 16 ($10) 16 ($10) 0-5 
STAHT ALDRESS (LOW) a ¢$00} © ($00) 6-7 
CURSOA {RICH) | 0 ($00) © (300) 6-5 
CURSOR (LOW) 0 {$00} 0 ($00) 0-7 
LIGHT PEN (HIGH) Q ($09) o (800) 0-5 
LIGHT PEN {£-0'%) O° ($00) 9 (300) 0-7 











Note that register | holds the horizontal display; this ls 40, not 80, as might be ex- 
pected, If this register is changed toe say 41, ty PORE $9520,%: POKE 59321.41 then 
the text will slope dingorially to the left, and the cursor moves in a erpblike dingonal 
direction, A pregram called 'CBM 4032 C CHEE’ reconfigures the 6032 as for vu 40-evlumn 
Mmuchine by (f presuaec) putting 20 into register 1. Register 9 controls the number of 
scana given to each character. 7 puts no blanks between adjacent lines; 9 puts 2. A 
value of 6 in this register ioses the bottom line of dots, Including lower-case decend- 
ers. A short program of the following type can be used to watch the effect of any 
register: 

10 PUKE 58520, :REM REGISTER MUMAER; CHOOSE O - 17 

20 FOR J = 0 TO 128 : REM OR CHOOSE OTHER LIMITS; TABLE ABOVE INDICATES MAXIMA 

30 POKE 59521,J: GET X¥: If X$«"K" THEN PAINT CHR${14}; END 

40 GET X$: IF AF<o" " GOTG 40 

$0 NEXT 
Each press of the space tar wil change the reyliter-value, Entry of 'X‘ at the key- 
board provides an ererguncy exit (just in case!) and roturos to nurmal, 

Kegistar @ control: the number of liues printed; if thew exreed’ 25. garbage 
appenth fran higher up the seteen memory. Register Id altese the atoet addrerss- oe 
streen ahifts lert with wraparouad. Kiyister LZ, holding 12jg, reverses We Keren! 
Su PORK $9520,72: POSE 59021,12 reverses the sereen, Replsters doand T between 
them central the pouden of the ehaructera on the screan, rether like herlzontal hold 
ona TV. PE have Gere unntle to get chiracters to cume oul in reverse, otihoayh 3 
‘tapact thls may be pescabta, 


AHI & mote Blink pyrcled control, and bit 6 gots Blink/non blink. 
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2:3 Graphics and the PET /CBM CROSS-REFERENCE TO CBM GRAPHICS CHARACTERS 

BASIC graphics Commodore has retained its set of graphic characters in all its KEY: | sn-$ sh-r ah-f sh-@ eh-c eh-d sh-e sh-# 

machines, including VIC. As we have seen, there are 128 graphics in total, or more if § CURS: 228 #210 196 192 195 196 197 227 

sone of the alphanumerics or punctuation symbols are included. They have not added PORE; 100 a2 64 67 68 

a high resolution facility, though hardware Is commercielly available which wilh do this. 73 

Some other machines have u 


70 so 8 
OOO 8B 68 8 


Sharps; and some, notably Apple, 








pgraded to high resvintion graphies, such as the hewer | 





| 
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have had high resolution, and colour, of a sort, ull KEY: sh-§ osh-t shew eh-b Gist aaa 4 eit 
elong, PET/CRM users generally have to do without elaborate Brapnics; Commodore has CHRS: Baus ate aa’. 3a8 as 7 89-103 
allocated such activity to its VIC evolutionary branch. CHM graphics displays usually i POSE; 101 na Ti 86 i Cl Cl 
have @ Prestel-like quality, apparently being made of a jigsaw of little bricka. The i ti | 1) aa} CO 2: Pi, Sets gee an 
character-generation aiso has an annoying defect, causing some adjacent blocks of ney: Pim a oe REVERSE, CHHE(18), THEN- 
reversed characters not to connect Properiy, leaving smalt lines. Nevertheless there xEY: ah-$ ah-/ eh-S sn-" sh-8 ah-7 sh-f sh-space 
are advantages in the CBM approach. Unlike external TY sets, the monitor picture is curs: 22a 42390 «©2490 2260184 183) 163 es 
Stable. Moreover the graphics are fast, since only one or two thousand fill the sereen, BORE: 100 #121 «121 98 248 247 227 224 
Apple high-resolition pictures need 8K of RAM storage. It is also possible to replace . Cl C! tl bea! — Ex | ae 
the character-generator with a fast EPROM containing (say} Prestel characters or sep PS ORE ERBE, CHES (18), THENS 
128 user-defined Braphies (the other J28 being thelr reversed farms). KEY: eal ened enue sKe* aRet "sh-apace | 
'Cross-reference to CBM graphies characters’ - see the table on the following | REN: it hy a nee is2 170 167 160 — } 
page - groups the individual graphics in a helpful way. There scems to be no method j CHRS: } 16 «117 97 246 234 221 224 
in the ordering of these cheructcrs in ROM, Note that, when reverse is taken into FORE: ty tT} 8 EB} yt ! Fe | t 
acvount, the sets of graphic type are all complete, with the exceptiun of the shaded {fi UO) &i tore es en 
dlocks. ;~ KEY: | sh-o sh-p sh-: sb-l sh-v sh-[ sh-n tae 
Programmers unused to the graphics set, or perhaps looking for ideas on huw : CHR: 207) 208 18G 204 214 219 205 ee | 
best te combine graphics characters, could to worse than experiment with a short POKE: 79 80 BR 76 bs s.00 
BASIC program like this: ! 1 OF FF ODO & EH : IN | 
10 POKE 59468,12: INPUT "LOWER CASE SET (¥/N)": ¥NS: IF YN$="y" THEN POKE ene rmere « = ohe- Bh-0 eh-. @b-1 sh-2 peh-3 sh-+ 
59468, 14 KEY: liad slate Pha 79 «ATL 
$ : 9 L173 176 «TH 177 LTA 179 
20 INPUT "CHARACTER STRING": x$ CURD} sp! 0 122 «11002«o113) Ld tS) LO? i 
30 FOR Js) TOS: X$=X$+X§; EXT: REM INCREASE LENCTH OF STRING FOR SPEED POKF: 12h 10% a ae a ay qo 
49 FOR J=1 TO 1000/LEN(X$); PRINT X5;; NEXT: RUN ae [S [A — marae | 








P , : : = ; | KEY; @b-< sh-> sh-, th-; eh-? 
This accepts input of a short string of graphics characters, then fills the screen with ‘ 190 488 172 187 191 
repetitions of the string. Interesting optical effects can be found: for example, the etna 126 1.24 «108 «129 °«2227 
Giagonsily-shaded squares in lower-case inode produce a herringbone pattern whieh PURE: i Ca a] ie" 
displays a woll-known optical illusion. A strin 1 ee as - A Bl — 
and sc on. Obviously, if the input string is 2 or 4 characters long, the resuit will be HEY: jah-k sh-j} sh-u sh-i gh-w  sh-q 
tectiineur, since each line will exactly repeat the previous ling. Otherwise, the patt- CHRS: 203° 202 2130 201 6215 «209 

7 

| 


ern naturally has a diugonai symmetry. Note that the POKE: 75 74 «=F 73 T 82 
Fi (4 f) (2 e) — 


g with format xxxyzzy may work well, 





prayraum is designed for n 49 
idunl characters. The 8092 is less 
amenable to graphics than its earlier counterpart; to display the full range, input a 
set of numbers {ave the table) und conyert then by CHRS inte a printable graphic 
equivalent, Also change the cunstaut bi fine 40 to 2000. Business keyboard users will 
find a number of graphics hard to obtain; the rather useful tines, permittluy boxed 
forwats, for example like the sercen pictured below, which is authentic Opart from the 
fipures, aren't obtainable by keyingc-in. This is because ahift-! theough shlft-? In the 
ASCIE table hive teen vombined typowriter-fushicn: shitt-l becomes ! rather than a 
T-shaped connecting graphic symbol, 
LEKINT PRICE A -Eot.-| 


Column machine; tine 40 prints atout & thousand indiy 





Bh-) eh-e ah-k owh-¢) ph-N 
169 «273 «4168 «168 = 220 





105-95) LOLs | 
P| Eo [Bo satiejed 


ph-a wh-s gi-z sh-x eh-f 
193 2i1 2:8 216 222 


ee 
| rs 
rt) 
*S) 


CHRY; aa o4 


eo @ BS oe 





; Gste (OD tt Yyos 1 1] etree ‘’ 
Friese Baegs : ; 

Rat tion Fe 
luther of 






PT or % al ai A) ee a | 
Ree ee penne ie 
: ry om i 








q 
NOTES, (1) Thera aro améigulties in many of tha CURZ figures « ee 
wigay Gusity wet bo chuasn. I've preferred the values with = constant ° 
28 troe the acre. POF, PEEK value. ; 
a ess hi the characters are made of A duta by Jd, « ling cannot peas au te ed 
the contre of any character; some charactere, when positioned aw perghtours, w t 
4 ugetoaor. 
ee ae ahs eae hag more then 64 entries, because gore eppear twice. Mote ane 
the lowsr-caag made spec gaa graphics + chequerad square, dingonally a apa a eae Pas 
iiniarh ruck or tick alga have nat been Included. The full t24 eta teal 
ohtsined hy reversing al) thoan ia the tattle, by ¥AIFItng the revereég cha ‘: 
Ar by POKRing the values Stated hora + 128, 


PO ee ee 

‘start Catstogie Humber s ' 
Fin}sr £3th at bee anikuer t ee } 5 
utar tits Fran Matnkeer y ; 


woe ter ts Forte Hutnber To 


CHMLCK Oe? ves ee ye 








. 


ew ee ee 


~~ en tPF ee eR A 
~~ nee TOOL ON SEPT ENDS Or ital ET were ee ere et ae ee er 
sett os hee ee es ~ aot 

a a me ey CE ee ee eee ee ee eee : 
Scan ett era at te ore - taqt dre Te TAM cece a a Abtenea (A Te oe TE 
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Programming the PET /CAM 


‘Digital clock’ is a reasonably short specimen graphics program: it converts TIS into 
larger characters, modeled on a T-segment LED or liquid-crystal display. Two type- 
faces, ordinary and ‘modern', are available! This program is in BASIC and is quite 
slow, so thut L second is sometimes not enough time to allow the time to be updated, so 
it will skip @ second. Also, of course, the progrum dons nothing else but ‘craw’ the 
clock. The suoroutine starting at line 10 draws a single numeral; it can be used to 
print any other numerals, where a display somewhat larger than normal is wanted, on 
a similar basis. 

Briefly, we wish to simulate diagram 1. A complete square ts nat availuble in the 
graphics set, 30 8 luyout like that in diagram 2 is needed, in which 5 adjacent squares 
control the final appearance. ['ve used the order D0,B,A.C.E.F of disgram 3; in this 
way, the cursor is always left in @ position tu start the next number, if there is one. 


H EH EEL 


Diagram 1 Diagram 2 Diagram 3 


if we make up a table with LO rows, one for each digit, we can write out the ASCII 
values required in segments A-E. Zero for example needs (A) Jaf ang El, or, in 
ASCH values, 164, 165,165,204 and 165, The five lines of subroutine in the program 
each process one of these segments, using a logical formula to embrace every value of 
numerst X. 

A decimal point can be allowed for; 

S000 1F MIDS(X$,J,2)="." THEN PRINT "Gt';: GOTO $020 shows the sort of thing. 


TAL LAX 


30Tu 1000 

PRINT MHRS (204 + 1728(Xe1 OR X24 OR X=7) + 40#(%23 OR K¥5 GR K=9)>F “CLEFTIC 
PRINT CHRE(Z04 4 L722 (X51) # 408(X22 OR X93) + B9e(X20 OR Xe7h02 “CLEFTICUPT 
PRINT CHRS(154 + Jree(X=1 GR X=4)); “COGWNI “+ 

PRINT CHREBCIOS + L39"(X=5 OR X26)0% “CLEFTICDOWNI"? 

PRINT CHRS(1S5 + ABS*#(X=2) 9 

REVUEN 

0 PRINT “CELRICDOWNI" 

lo xs © 11S ; 


20 FOR t 9 1 TO 6 STEP 

25 FOR K * O TO 1 

30 Xo & VAL( MEDS(XSeT+Ke 1d) 3+ COSUB 10 
40 NEXT Ke PRINT". "is NEXT I 

50 RPRINT "“{HOMEIC DOWN)" 

49 GOTU 1010 

oY 


ILAR ROUTINE WEiTH COMPUTER~STYLE TYPEFACE 


PRINT CURS(204 + 1728(K"1 OR Xed OR X¥7) + 2PHIXAI OR Mes OR X95) t “CLEFTIE 


i 
PRINT CHRO(204 # 172"(Xe1) + 498(X02 OR Xe) + 24e( XO OR xed) “CLEFTICUF) 


"t DOWNS" 
“CLEFT ICOOWNI"s 


PRINT CHRS(tS4 9 12e(Xat GR ka4h0e 
PRINT CHRU(IBO © 146e¢XeS CR XeG)OT 
PRINT CHRO(1LQ0 * 1408(X"2)06 

RETURN 


IO rte Sop Re mem aman ee A atm eR SE A mt NE Lk RAE TS ST Agee A IRD ir fs arti me ~ 


- ged ato Se a voy, eh o . os oct, 


ee ee 


Fe EE TRY I ee REI TSI pre  rrert gi be eae SP aa ae PP PND I TY Ba a 


TN errr 
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Special features of BASIC 4 screen handling, BASIC 4 machines are more complex 
than their predecessors, There are currently three distinct models: the 8032, which 
has 80 columns; the 8" screen 4022 (and 4016, 4008), which is no longer manufactured, 
and the 12" sereen 2032 (and 4016, 4008). The 80-column machine has the most feat- 
ures, lergely because a chunk of KAM previousty used for sereen-line tables is not 
needed, This enables it to be equipped with several features not obtainable on any 
other machines, even those with BASIC 4, notably a definable screen 'windey'. These 
differences are made possible by varying the ROM which deals with EQQQ- EFF. The 
presence of the CRT controller chip distinguishes 12" sercen machines from the earlier 
&" modeis. 


Text/ graphics 12° machines have machine-code which both sets the CRT and puts 
the character-generator into the appropriate mode, Fur ‘wraphics', the lines are moved 
so as to be adjacent, and upper-case/ graphics mode is selected; in ‘text’, or ‘lower- 
cast’ mode, the process {s reversed. PHINT CHR$(14) selects text mode, the value 44 
was presomahly suggested by Lhe usc of FOKE 59468,34 to select lower-case node, 
PRINT CHES(142) sets graphics. The ROM routine can be called directly, with s¥s 
87368 or SYS 57371. The [ESCAPE] key allows yet another varintion; 'n' is the 14th 
letter of the alphabet, so PRINT "(ESCAPE JUNSHIFTED-N has the effect of PRINT CHA$(14>. 
and PRINT "(ESCAPE][R¥SJUNSHIFTHD-N acts like PRINT CHRS(142). 


9032 screen windaw One screen window only may be defined at any one tiac; however 
the redefinition time is small, so there is little difficulty fn apparently generating such 
windows at wil anywhere on the screen. When a window is defined, four RAM para- 
meters are set: locations $E1 and $05 (225 and 213 in decimal) hold the screen pas- 
itions of the bottom and right cf the window; $60 and $E2 (224 and 226) hold the top 
and left. The top and ieft parameters have a minimum vatue of zero, corresponding 
to the topmost ling and teftmust sereen position. The bottom haa a maximum of 24, 
and the right a maximum of 79, If these values are exceeded, garbege will appear on 
the screen when it serolls, and information at the rigntmost end of lines will be lost. 
If the battem parameter is less than or equal to the top, or if the right is less than 
or equal to the Ieft, a single row or column only is printuble, A window must have @ 
certain miniaum width to be ussble. For example, RUN(HETURN] needs at least 4 cal- 
umns, A hurruver window wil not permit the command RUN to operate. 

The paranicters may be poked into the iccations given, or the speciatiy allocated 
characters may be printed: PRINT CHR$(15) makes the cursor's current position into 
the window’s top-left, and PRINT CKR$(143) sets the bottom-right. 

A window is erased by twe consecutive [HOME)s. which are counted in RAM 
location $K8 (=232 in decimal). 








49 to 80 column interconversion 40-column programs can be run on the §8-column 
machine by redining the sercen with the CRT chip, as previously mentioned. Generally 
the reverse process iy impossible, because 80-column software requires 2000 bytos of 
screen RAM, which the smalier-sercen machines do not have. However, by editing 

the larger-sereet output, provided its total storage requirement isn'ttoo Jarge, conver- 
gion to the smaller format muy be possible, 40-culumn software may run without nod- 
Klentiong on $f-column machines: if only PRINT statements are used, and if these are 
terminuted with carringe returns, the output whl ulfyn itsell down the left half of the 
screen, When PRIST is fullowed by '3' ,relying on the end of the ecreen to force 
printing on the next line, its tine will extend across the screen. Direct pokes Inte 
ferenn KAM fill the top holf of the screen. Either of these latter possibilities can be 
avoided by CRT reconfiguration. 


Other sereen-editing characters in BASIC 4 Apart from TAUs, BASIC 4's new screen 
editing cummands wre; 
PRINT CNR9(21)) Palate dine from sereen 
PAINT CHI3{22) rage fine up to end PRINT CKRS(350) Erase line From Blert 
PAINT ChA$(25) Serotll screen up PRINT CHR$(L63) Serall screen down 
Thess muy be enaier to use ffoa atring Is defined to store the approprinte chinracters; 
ADS-CPN$(454) is innemonicnily hulpfut by PRINT Sb. 


Halo TANS PRINT CORECLST; ats A tab postition; PRINT CHRSCB) kieves the cursur ta the 
next tab puslieu, or te the end of (ha Line. However. df a tob fa atrendy set at that 
Postion, PRINT GHRBCLAT) wraeta it. ‘Tab dali fa etored in tum bylea of RAM, Just 
telow HASIC. (See Chapter ie RAM aapd. Kach of the eighty bits may be bor 0, 
and forlenetea ep dnl aettiagt, The first byte ptares (eta for ecluman @ 7, the Reoonl 
for #14. and ao un. flaweger, the bila afta arranged in the reveru: urcer, oo poking 
the first Wyte with Canyd 2 eois a tab nent tho deft of ila set of culumna, 


PRINT CHR$(110) Insert Ine inle sereen 






fiir an aimgsder, 
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Machine-code graphics As we've seen, BASIC is liable to be slow when dealing with 
graphics. In this section we'll look at machine-cove graphics, which enable graphics 
effects ta be reolised in e far faster manner. This will have to be shipped by those 
not yet familiar with machine-code; nonethciess muny of the examples can be entered 
end run by mexperienced programmers, 

Machine-code is chiefly used (with graphics) to put characters directly into 
ooreen RAM, rather than PRINTing them with FFD2 or a similar output routine. The 
beginner, to understand this idea, can enter this shart program into the machine with 
the monitor: 

Eater SYS 4; the monitor now displays the program counter and other reglaters. 

Enter HW QO33A 6342; two Llnes from the mactitne (16 bytes tn all) are printed In 

two lines. Tuis 1s the start cf the second cassette buffer; in BASIC«4 it ts 

tnviclate, unless the socond external cassette port is used; in BASIC 4 1t 
storey sowe disk data, but in our example this ian't important. Now type in: 

K O33A AZ Of BA 9D 00 #0 Ed 10 

@O242 Fa 60 

Enter X to return to BASIC. 





tha remaining symbola are unimportant. 


$033A (=826) is now the starting-point for the following machine-code: 


LDX #00 iload register X with value zero 

TKA itransfer cuntenta of KF to é 

STA 800G6,% ;store accumulator contents into address $x000 + offset in X 
INK pincremeant = 

BNE -7 ;if X ts nonzero, branch back 7 (count from RTS) to TXA 
RTS iFeturn when X is zero - after 256 tvoops. 


Now SYS 825 pokes 256 values, from 0-255, into the top of the screen. They should 
correspond to the table of screen poke values a few pages back, Note the greatly in- 
creased speed with which characters are printed to the screen. This program is short 
because its values are computed; they needn't be looked up. The next example pokes 
the word ‘hclic' into the screen, in lower- or upper- ease depending on the mode: 


a re 


¥ f gies les te pent aby 
Kk 0350 Az (O4)P0 58 03 90/23 a1)—» nt. sheng as 
M0358 CA DG FY 60(08 05 OC"OC ROL x ae r. Le net, 
M 0360 OF Leap ate nyt, 


When this routine is entered, SYS 848 prints ‘hello’, starting at $6125. The table of 5 
bytes holding ‘hello’ appears after 60, which ts the RTS opcode, Ajain, the beginner 
is recommended to try this; it is quite easy to understand, The values ringed can be 
changed freely, and the result examined. 


Screen reversal and flashing. These effecta are easy to get in machine-code, 
subject to the usual problem of managing RAM se that the routine doesn't occupy 
space taken up by other routines, We haye alreudy seen that the high bit of sercen 
RAM characters detemines whether the cheeactcr is reversed or not. To reverse an 
entire acreen, therefore, all we need to do Is scan the entire serecn RAM, replacing 
every charactor by its equivalent with the high Lit reversed. Hf we repeat the process 
the screen wiil return to its previous condition. Note that this method reversey off 
characters; If they ere reversed already, our routine wil return them to the unrey- 
ersad state, 


LBA #86 
BTA Ot 
LDA #00 
5TA 09 jindirect addresa (G0) palnta to $060 now 
Lk LOY #00); thin loop procensen one pays (250 bytes) of acroen 


L2 «LDA (90),¥ithta toop usem ¥ ta count from 4-295 
TOR #60 
STA (09).¥;poka reverend valun back tnto tne xcrean 
INY 
BSE b2 
Inc 01 pdadtrect address (80) prints to $8190, $4200, ete. 
LDA C1 
Cur BL 
BNR LI 
ats 


setep when $8400 reached; SO-colusn machines wae @RS 


. 


ia aR Le oot ob el al tia a The haat atl oe ae die eee at aad ancient tener tal ae ae ee 
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This machine-cude (not quite identice! - a tighter version} reverses the screen; 


: 1 pase 
WO93A AO CO 1 02 A2(B3)95 02 —~B7 Ge FO-GrmeR mane, 


0342 Bl O1 49 #0 91 OL GS DO 
ODtA F7 CA 3O F2 60 -any--- 


So SYS 826 reverses the screen (in 1/50th second or 1/25th with 80-columns}, and 
10 FOR J v1 TO 10: SYS 826: NEXT flashes the screen ten tines, leaving it unreversed. 
This code is relocatable (i.e. can be entered unchanged onywhere im RAM), locations 
land 2 are used, so USR jumps will co longer work until thei correct Jump address 
is loaded. , ; ; 

fs it possfole to reverse only part of the screen? This too is quite easy. Let's 
suppose we have the starting address (A.g $8050) of the repion to be reversed, and 
let's suppose we want a certain number of bytes (<256) after the starting eddress to 
reverse; for example, 40 or 8U bytes will reverse one line of text. The following short 
routine, also relocatable mechine-code (for a change, I've put it at the start of the 
first cassette buffer, starting $027A), and demonstration BASIC driver program is one 
way of doing this: 


M O27A Ad OO 88 BI GU) 49 80 al 
0282 01 98 DO Fé 60 -~any-- 


1000 POKE 0,20 +REM O HOLDS NUMBER OF CHARACTERS, SAY 20, AS RFRE 


1010 POKE 1,80: POKES 2,126 :REM (QL) POINTS TO $8050 
1020 SYS 634 “REM REVEHSE 20 CHARACTERS FROM $8050 ON 


Different effects can be ohtained by modifying the core of all these routines, 
whieh is LDA trom ea addresa’ EOR #99 to switch the high bit/ STA back into addrees. 
For example, AND #7F unreverses the entire screen; ORA #80 puts every character in 
reverse form: EOR #40 switches all shifted characters to unshifted, and vice versa; 

INC address (e.g. INCCUL},¥ /NOP /NOP/ NOP/ NOP) replaces every character by the next 
Character in the screen KAM tuble. 

Note that all these examples use purely software methods. When the screcn 
scrolls, the reversed text will scroll up with it, leaving normal text. ; 

Uaing switches. With the help of the interrupt routine, we can call up machine 
code routines with o simple poke; this provides a convenient way to eall a batch of 
routines. For example, we may have ten stored szreens of data; poking a preset loc- 
atios with 1-10 cun autometically display any of them. To show the method, fli assume 
that the routine at the top of this page is present in RAM. We can use O44¥ ag the key 


location. Then enter: 
M0350 AD 4F 03 DO O03 4C 33. E4 
03248 20 3A 03 10 FB ~-sny-- 
Now enter .R, to display the ragisters, and change {#Q from B453 or £62F or EGS 
to 0350. The IRQ vector ian‘t changed until a CO command, so enter ,G@ 0004 to 
BAK. Now, thia machine-code is processed at every interrupt: 


BASIC 2: 28 B6, BASIC 1: 85 F6 


Q350 LDA O341F 

0353 BME 0358 

0345 JMP E455; OG ES2E OR £085 

0358 JSR OJDAsexecutes pubrouting xt O33A, in this cava acreon reverew 
0358 HPL O345;unceaditional branch, because of G23A's mothod of operation. 


When $034F (-847) is POKEd with any non-zero value, the screen Is reversed at cach 
Interrupt; therefore the screen flashes, and processing tlso slows down a yrent dani 
besaune there are 59 or 69 Inlerrupls per secand, and our routine takes 1/25th or 
ISuh of no neconed to can! POKE 847.0 stops the Mashing, The routine at $0350 14 eauy 
te extend so thet da perhapa reversed the seruen onea, or reversed Stone teen when on 
la poked dite f'4E.  The rev’ paint, however, is the relative case ty which alerOHe 
Irion eng be valted Uke thin; (ida in ne teas in mactiine cade ag BASIC, A value oF a ins 
adoeation might sivnal Ghat nothing da to be done; viadues Ervin 1-16 might tira etiteet 
Rumber ¢ in any of sitieen proaet positions on the serecn, vues of Li-ai mark de 
the myae for ungthes etdect, und sa on. Tf necessary die Interrupt cay teat several 
lueations, "Space Tayadera’ in ite PET SCM version uae a techalque ike this. Tavlng; 
soon a few meteade at work, we can consider sorts of the punlished work on graphics. 


me ee pen cede ne NR, MUL Mae re eat nL RENT er Teen tomate Mima roo en : 
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Published utilities. Compute!’ (March '81; Vol.3,#3) hag a six-page article by 
D Malmberg including machine-code (long) and BASIC enabling one rectangle at a time 
to bu filled with a character, reversed, or made to Mash: and also to be shifted else 
where Lodity, shifted continuously or ‘made to grow or shrink in size’. This last feat- 
ure means that, a5 a rectanwle moves, its previous incurnations are left.on the screen, 
not erased. D Simona (CFUCN Vol.3,#2) has a long routine, for BASIC 2, which inter- 
cepts AASIC, providing various sereen facilities, including the interchange of two 
screens in RAM, and verticai-bar graphics. ‘'Frintout' (Jun.‘'d1) has a few routines, 
taken from "PET User Notes'. CCN (Vol.3,49) has some machine-code, withaut, how- 
ever, instructions on using it. Frobably, if you have access to back issues of journals, 
you cen find mare. Don't expect much though; you may be disappointed. A different 
Style of screen image processing is represented by ‘systematic routines’, as I've called 
them, for lack of a betler name, These inelude 'SET', which plots double-density dots 
on the screen (see Chupter 5). 








Systematic machine-cod+ utilities Three pages before this you'll find a table entitled 
‘Cross-reference to CBM graphics characters’. From the layout, notably of the topmost 
rows, it is clear that the completeness of the graphics character sets enables some 
progress to be made towards high resolution graphics. SET (in Chapter 5) exploits the 
fact that all sixteen combinations of squares with internal quadrants exist on the PET/ 
CBM; the machine-cocde hus a table of the appropriute values built in, Similarly, e CBM 
manual has a demonstration prograin including a histogram of US national income, in 
which the horizontal bars include, at the end, fractions of u square, as listed in the 
fourth row of the graphics chart. D Simons’ ‘Super BASIC’ (see reference above) in- 
eludes a routine to plot vertical bars in the same way. And some EPROMs, e.g. the 
‘PieChip', include routines tu approximate curved lines with short segments, taken 
from the first and second rows of the chart. To show the methods which such pro- 
grams vse, let's write a routine to plot vertical bars in histogram-fashion, to the 
nearest 2/8th of a square, i.e, including for 0-7 rows of dots on top of each column of 
solid chnracters. For this, the third row in 'Cross-reference’ is needed. i sha!l assume 
that the starting-point in the screen (e.g $8300, the bottom-Ieft of a 46-column screen) 
ts stored in the two bytes ($91), and that the height of the column is stared in $00, 
so that a ‘height’ of 20 mearfs 2 solid squares (making 16 rows of dots) topped by 
CHR4(226), adding the final 4 rows of dots, 


LDY #00 
Li Lpa 090 
CP #08 
BCC +23 
S3c #08 
STA 0O 
LDA #AQ 
BTA {01),¥:; put reverse-space into screen 
LDA Oi 
BBC #26 
STr OL 
LDA 02 
sax #00 
STA 02 
Bea LL 


sexit routine when this value in zero to seven at L2 


:gsubteact 40,9. 80-column wachines use £50 tustend. 


unconditional branch back to continue 

L2 TAX iA and X hold value 0-7, which now becomes the tebie's offsat 
BEQ L2 jdun*t plat if sero.,, 
LDA TABLE, X,otherwlea, toad Xth value from tuble {hetlda row J poxe valves). 
BTA (01), Yintore Final few rows of dots 

L2 ARYA 
TABLE #04 #0F 679 #62 WES RPT FED jin decinat, 105,114,121, 08, 246,217, 227 


The routine relocates, end workr with all BASICS ¢fn graphica moda}. It looks like 


TIRES ig G27A AU OG AS fi C2 OR OU 16 


0243 FY OB HS 00 AX AO B1 OL 
028A AS U1 BU(ZH, U3 GL AD O2 
0292 ED 00 B4 U2 HU R4 AA FO 
G20A 05 BD AD G2 91 01 60 64 
O2A2 OF 70 62 FR YT DT -any- 


So POKER UM: POKER 1,P: PORE 2,41 ;8Y8 834 drawn a column of helght tf an 38300 ¢ Pp, 


= Su unth 80-cnlann w whines 
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Using '‘SET'. The disassembled version of SZT is too long for inclusion here; its 
method, briefly, invotves (i) Calculating the position in the screen which corresponds 
to X-coordinate and Y-coordinate: (ii) Loading the character at that screen posthien; 
Gil) Modifying it, by GRing the offsets in thy table of #6 characters together; (iv) 
Replacing the character with a new one, with one quadrant changed for nothing chang- 
ed if the dot alrendy exists). ; 
Instructions for BOM modifications and relocation apperr in Chapter 5. Note thst 
the X- and Y-coordinutes, stored in $0U and S01, are changed in the course of the 
routhie's execution, anc must be entered afresh for each plot. Any characters in the 
sereen which are not in the lookup table (i.e. everything except the sixtven graphics 
characters which are part of the set of quadrants) causes nothing to happen, so that 
leetering on graphs is ignored. Obviously, because lovrtions O - 2 are utilised, it is 
necessary if USR subroutines are called from BASIC to poke the jump byte ($4C 276) 
into 0, and the indirect address into (01). Its worth noting that the character gener: 
ating ROM has defects which show up in this instruction. Keverse- shift-> , shift-; 
and shift-? do not abut correctly to reverse-space, leaving little vertical lines, 
Demonstration programs. ‘Coni¢ sections’ is a mathematical routine, which draws 
a canic section from 6 general parameters. [t includes a subroutine to enlarge and 
reduce the scale on which the conic section is plotted; the limits un the X-axis are 
shown on the sereen. In this way (with luck) a conic section can Le viewed at a 
reasonable scale. It is interesting to sce how the two branches of a hyperbola appear, 
when reduced in scale, as iitersecting straight lines. Some equativns, of course, ore 
incapable ef being plotted, having only inayinary solutions, The program simply 
calculates $0 solutions to a quadrulic, scanning trom left to right, and plotting the 
result if it exists, and fits into the current screen's limits. Line 508'y function is 
the sign; its function is mainly cosmetic. The seating factors have to convert any 
range of X values into 0-79. For exumple, X limits of 20 to 50 are transformed $o 
that X=20 becomes 0, X=50 becomey 79; at 1/10seate the transformation is recelculated 
so that -115 to 150 is the range for which X becomes 0- 79. An 80-column machine 
requires a few changes, to lines 10 and 510. 


DOUBLE DENSITY CONTC SECTIONS PLOTTZR Feb 81 





G PRINT [CLEAR] [REVS}NOTE{[RVSO] NEEDS “RIRES $0334" TO BE LOADED"; WAIT 158,12: RE 


MK OWARNS 

2 GOTO 509 

10 FOR 1 = O TO 79: X = XL + IMGF ; 

20 LR CeO THAN AL@FNAL(X}: A2=FWA2(K): Ye+A2Z/AL: COTO 56 

JO AL « ais 

31 A2 = PNAIZ{X)/C : F 

35 IF AL*Al ¢ 4SA2 THEN NEXL: GOTO 110: REM FASTER THAN “coTO 100 

49 AJ ~ SOR(AL*AL~4*A2) 2 . 

$0 . panies *PEM DLIVLSOR 266 IS A SCALE CORRECTION {7OR ROUND CIRCLES!) 

Si ¥ =25 + ¥/SF 

52 IF Yrl AND Y<5G THEN POZE O,[1 POKR 1,%: S¥5 626 

$5. ¥ = (-AI-A2)/2-6: REM TRIS LS THE OTHER SGLUTLON O THE QUADRATIC 

56 ¥ = 25 + Y/S5F os 

58 1F Yol AND Y<5O THEN POKE 0,0: POKE 1,¥: SYS 826 

Eh NEXT 

. : ‘7 

110 LREST" (HOME) foOwN] THOWN) (GOWN) [DOWN] [DOWN] (DOWN) [DOWN] [LOWY] [DOWN } [DOWN] (DOWN) (D6 
NI POA | ast) He (DOWN | (DOWN) (DOWN) (DOWN} [DOWN] [DOWN] [DOWN ]O (EXT) / ERLARGEMENT 
FACTOR" SAL 

115 [Fy Al + G GOTO 1H9 

120 $2 = (A2441)/2: SI = (K2-K1)/2 

iW XI © §2-SU/Al: X2 = S2495/Al: COTO 310 

50% PRINTMCORFEICFENTS OF A,B,0,D,F,P 2:INPUT A, B, C, 9, E, F 

$2 tert “LATTIAL LIMIV7 GP XT,Y2 ARE“GNL, XZ 

304 NEF PM ALIX) = (HA + BD 

SAA OUR EN ADIX) = CASTOR + NEN + FY 

50% GER OPM SGEMD = = CKOOD FAS = (Hot) 443 

S10 SP e {42-X10/79 1 BEA SCALE FACTOR . ; 

517 PRINT “TCLEARI" | At “eLPeT Ie 2": Ms CHKSCENSG(B)}; “ %p MEDS(STRS(B},2)¢ "RV" S 

SED PENT My CHPSLRMEG (GHD: Mp MEDGCSTROCED 235 ar a ee ot sie. 

S14 PV IMT CHAS{ PR UG fE pg TO MIDS(STRS CO)» 235 cy 1 CHRSCRESE CZ : 

S26 PRINT MIDS? 85 (0). 2b, "Ye SG nF : 

S18 PRINT mHK Ie"; BONEN) MINT (ABS (RID EAT) STO"; SGNCUZISTNTCABS(K2DS0T}5 Ol 

$74 (asta LA 


ee eta oo nse ee ne ee me, et 
Se ae eT DD a oe a 2 ethan ene 
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Extensions. An obvious addition to SET is a command to plot ‘straight lines', 
i.e, small Squares a5 nearly straight as the resolution will allow. There is insufficient 
epace here te go into details, (CPUCN Voi.3, #2 has a 40-col, routine by D Middleton). 
The algorithm is reasonably straightforward; something like thls is required: 

(i) arcange the end-points u,b end c,d so thet a is lesa than or equal toc, 

ii} Test asc and b-d; if true, plot one point only and exit. 

Gii} {s ABS(d-b} > ABS(c-8)? Hf so, the gradient, either up or down, is steeper 
tha t. Branch to one of two routines depending on the gradient: 

(iv) Gradients=1, Every horizontal position will have a corresponding paint; 


9: Grophics and sound 


Piet a,b. Increment a; if it exceeds c, exit. 
Culcutate the next b = b + x-increment*(d-b)/{c-a). 
Go back to plot a,b again. 
tv} Gradient > }. Test for a vertical line; if found, draw it with its own sub- 
routine. "Vertical includes nearly vertical lines, which otherwise will be too short. 
Increment vertical positions, not horizontals, like this; 


4 Plot a,t. Increment b, calcutate the nearest 4, 
: end continue until & exceeds d. 


'SET' is slower than it need be: @ lookup table for screen lines saves time in 
performing calculations, but eccupies more space. The slowest part of the routine is 
the search for one of the sixteun characters, With CBM ROMs this process iy inevitable 
because of the unordered arrangement of the relevant graphics screen form. A system 
in which the screen value corresponded to the graphic's appearence (e.g. FOKE 0 
giving a blank, POKE i e single quadrant in the tov left. ete.) would be faster. 

Demonstrations. Finally, a few more simple BASIC demonstration programs, Some 
of the results ere Mustrated on the next page. 


HIGH RESOLUTION GRAPHICS DEMONSTRATIONS (ASSUMING SYE B24) 


400 FOR § « 6 TO 2 STEP -1 

410 FUR X 2 0 10 79 STEP J: FOR ¥ © O TO 49 STEP Ji POKE OrXt FOKE 1+¥ 
420 SYS 8261 NEXT Ys Xs J: ND 

500 FOR J = 60 TO @ STEP -1 

510 FOR X = 0 TO 79 STEP Ji FOR Y = O TO 49 STEP J: POKE OrXt POKE 1-¥ 
$70 S¥S B26: NEXT Ye Xs de END 

600 DEF FN Y{X) * 25 + X#SINCX/3)/10 

410 Fuk * «© O TO 791 ¥ © ENY({K)a IF ¥ ¢ O OR ¥ ) 255 THEN 630 
420 PIKE O,Xs POKE 1+%1 SYS 826 

630 NEXT 

640 ENE 

700 DEF EN ¥OX) © 25 4 SIN(X/20)#COS(X/10)425 

710 FUR X *® 0 TO 79%) Y¥ * FNYO(X)s IF ¥4G GR ¥I25S5 THEN 730 
720 FURL teks POKE 2+¥0 SYS A2ZG& 

73Q NEXT END 

800 PEF FNY x deXed 

@10 FOR J = 9 TO 2 TEP «2 

820 FOR € * O TO 791 ¥ « FNYEXS: IF ¥(O OR ¥2Z55 THEN 840 

830 FHKE O-X+ FOKE Lr ¥1 SYS 826 

840 NEXT XT 

450 END 

900 INPUT NO.OF PETALS iMe INPUT “STEP StZb .GL-20°18P 

710 EF Mos ENTOM/2)e2THFN Mo» M/Z 

Pro TOR Tee» O 1G tem GTER uP 

730 S$ = CLIN(TH#Mdteo - 
940 Xe Geary «© SeSUNG TH) 

FSO Ks 40eFaexXr Yo # 25 e20K¥ 

POO PUKE Cts CURE te Ye SYR O24 

770 WEXT 


7 
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9.8 Dumping PET/CBM graphics to a printer 'DUMP', in Chapter 5, has a program 


to scan and print the screen to non-CBM printers; graphics characters are printed 
as '' or some other symbol, to show that they exist, but cannot be printed. The 
BASIC routine below will print sereen produced by SET to any printer; the top and 
botlom halves of cach character are printed as ' etre or ee, 


LISTING OF “HT RESOLUTION” PLOTTING PROGRAM 








O PRINT"LOAD SCREEN WITH PICTURE TO BE PRINTED [N LINE O00": END 

10 OPEN 4,4: CMD4: REM PRINTER OPENED AND @FADY 

20 SCREFN = 944096: REM START OF SCREEN 

40 FOR ¥= 0 TO 24: Kit SWEEP VERTICAL POSITIONS OF SCREEN 

40 FOR R = 0 TO 39: REM SWEEP HORIZONTALLY AND PRINT HIGH HAL? OF CHARACTER 
50 CH = PEEK (SC+ 40*V + A) ; REM ASCIL VALUE OF CHARACTER ON SCREEN 
60 IF CHe32 OR CAeSs OR CH=108 OR CH=123 THEN PRINT “ "5; :GOTO 100 
30 LF CH=124 OR C4225 OR CR#254 OR CH=Z55 THEN PRINT * *"; :COTO 100 
80 IF CH=97 OR CH<126 OR CH=127 OR CHe2S2 THEN PRINT "* "5 :GOTO 100 
90 LF CH=160 02 CH=226 OX CH=236 OR CH=Z51 THEN PRINT "*R"S 

100 NEXT A 

110 PRINT 

140 FOR H = 0 TO 29: REM SWEEP HORIZONTALLY AND PRINT LOW HALF O# CHARACTER 
150 CH = PEER (SC+ 40*Y +H) : REM ASCI] VALUE OF CHARACTER ON SCREEN 
160 IF CH=32 OR CHwi24 O28 CR=i26 OR CH=226 THEN PRINT " "; :GOTO 200 
170 LF CH=108 OR CH=127 OR Ce?25 OR CH=Z51 THN PRINT " 4"; :GOTO 200 
180 LF CH=97 OR CH*L23 UR CH=235 OR CH=255 THEN PRINT "* "; :GOTO 200 
190 TF CH=98 OR CH¥160 OR CH¥252 OR CHe254 THEN PRINT "#4"; 

209 NEAT H 

210 PRINT 

250 NEXT V 

260 CLOSE 4: END 








a cochushie singh OSGCa RE OR NR aia em ec ar ey <A en iM in Se = ap Ma hee er ete om 
sete pee ct ce Sere 


ar pete gee 
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Users with Commodore printers can of course reproduce the entire graphics set on 
paper. This machine-code program, ‘Keyprint', is the BASIC 4 version of a routine 
wlich has appeared twice in ‘Computet', in March '8t (Vol,3, #3) for BASIC 1, and in 
Nov. /Dee.'80 (Vol.2,#4) for BASIC 2, 


'KEYPRINT’ (BASIC 4) 


+! O27A 78 AD O02 BS OL AS BS 4S 
+: 0282 90 $8 60 AS 97 CO(2: D0; Charactir (4g . backslash), 
+! 028A 03 20 92 02 4C 55 Ed Ag 

-t G29¢ 80 85 20 AG OO #5 IF AD 

+: O29A 04 85 BO &5 D4 20 05 Fo 

+i O2A2 20 48 FL AD 19 8S 22 Ad 

+: Q2AA OD BS 21 20 O2 FF AO 11 

++ 0282 AE 4C £8 £0 OC DO 02 AB 

: OZBA 91 20 D2 FF AQ OO BIOLF 

+: 0202 29 7F AA B1 IF 45 221 10 

+t O2CA OB BL iF 85 21 29 BO 49 

+i 02D2 92 20 D2 PF 8A C9 20 HO ‘ 

«1 @2DA 04 09 40 DO OF C9 40 YY ~~ 
+1 O282 OA C9 60 BO 04 09 BD DO 

-1 O2EA 02 49 CO 20 D2 FF CE CO 

+! 02F2(@8)90 CH AS 1F 69 27 85; Cotenns G2 or 6A) 
«1 O2FA LF 90 02 kB 20 C6 22 DO 

+1 0302 AB AS OD 20 D2 FF 4C cc 

+! O30A FF 


:Points to $0285 here 


Points to $0291 & (2Q 


Notes: 

(1} Has no test for ‘stop'; if inudvertently atarted, switeh off the priater. 

[2] Designed for upper cease with graphics mode. 

(3] The marked byte controla the width of the output: change this to #$50 (80 in 
Gecimal) with $092 machines, else you'll get 50 Lines of 40 characters, 

{4] Tho other marked byte controla the character which starta the print at any 
time during program running, Tue backslash character is #$2F in location $97 
with 8032 wachines, hut #$i5 io othors, becauge of differences in the 
keydoard organisation. 

(S] Calling $027A (by S¥a 034) redirects the IRQ vector sc every sixtieth of a 
@econd backslash is tested for, and, if found, the progru> stops whtle the 
entire acreen is duaped Obviuusly, if the IRQ vector is Teeet, by you or 
by tape activity, or if the interrupt 18 off, 'keyprint’ wan't work, 

{6} This is positioned in cassette buffer #1, for compatibility with disks (wuden 
an BASIC 4 use porta of byvter #2} and external Cassettas (device 2). A few 
early ed¢rensea need changing to relocate the routine, 


9.5. Animation Before examining programming methods, iet‘'s briefly look at some of 
the stuck~in-trade methods of animators, * 

Broadly spenking, the sbjeet is to get an impression geross al feast expense. (n 
practice this means using ex much tepetition as possible, as few elaborate drawings, 
and as few frames-per-second as looks reasonable, Signifleant fcotures are enlarged, 
e.g. head, nose, eyes; less inportnat features ara BbuppresHed, The overall figure must 
have its configuration of (sty) arms, legs and body correct with respect ta the ceatre 
of gravity, {f motlon is to be fugyesteg. Foo many ‘in-between’ should be avuiced: 

a stylised face muy have only a profile or full-face, perhaps a 3/4 fren, Symhots wil 
obviously be needed; 'Microchuss' successfully used very slyliaed chess piewes in its 
PET version. ‘Space Invaders! hag led fo the uveeplunee of things vier busluad4 of 
Pevple and orange Inwninowers whineing around serenas. An octiely by an ndverliser, 

D Kona (‘Crenthys Compating',dan.'#l) linte rules of thustb for eyecktoning agin 





‘Computer Srapdica gan produce yory impressive {and expenaive) effects: none aimulatere 
for alr and wen palate navn renl-tina displays in talour of venelderatle reoiiesn, Some 
Wort comet UN univereitiea, and the Sow York Tech, are renowned fur thatr #urk 

in tht» field, Bro (e.g) "Principlew of Interactive Computer Graphica’ (Newnan & 
Sprovll, McGraw-Hill}, whieh ie however Hoavily mathenationl, Work of thie type, which 
@ay involve data tranafer rates of many Wagebytes por second, 1# nuteide the Capacity 
ot present microcomputera, 


. 
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largely based on the idea that any motion attracts attention. ("If it moves, salute it’ is 
@ biological imperative not confined to the quarter-¢nck"- G Spencer Brown). 


Se ag en ee ee ee 
SR Te ena 
cone MAC) Ten Be | we 


flees | 


. i} 

Paraphrasing this and other articles gives ‘rules’ something to this Pla 

i. Always have something on the screen (i.e. don't just clear ry. * 

ti. Always have movement of sane kind, blinking or flashing gaat € ae er 

iii, Vary the speed (but keep it at at least Mmedium-pace) and vary s Aa fed - 
lettering - large, small. overwriting, rolling Tight-to-left, 3-D~ and eect ue a 
objects, Words giay appear on a board, within a speech balloon, from an ‘alphabet 

M a gun. ; : 

Bits “ss Bich een dull things may be animstable; Ross quotes & piper nih a 
flickering flame’ and ‘brend popping from e toaster’. The BASIC loader a Sup er 
puts numbers in the top left cf the screen, so you have something to watch. 











machine, a maximum of about 3) different screens can be held in RAM smoulanegusly) 
this is more than enough to provide good auimetions of such things me it ea e 
worst part of such a program is the effort of ‘drawing and storing the ah deem 6 
gereens. Once they have been stored in RAM - it’s sensible to practise § or ing iva 
disk before all thea stork of entering them - they can be displayed by a eg aioe - 
the following machine-code. ['ve assumed that the screens are arranged in I- see 
starting just below screen RAM; adjustments for non- 32K and non-40 ene un Bs : 
aren't too difficult. The start of each screen therefore is ea block of deals SEE 
page. For convenience I've erbitrarily numbered the screens in ene o ages 
aiarting 1, The object is to access any screen easily; let's use the i ea i. a : ara 
80 that a POKE into some key location with 3, say. instantly Cae ereee ‘ ut aay 
it's easy ta control the animation in either machine-code or BASIC; for see € eh : 
needs only something likc: 16 FOR J=i TO 10: PORE €34,J; NEXT: GOTG 10 to Show 


screens in sequence. 





-.  Ts7000 |$7400 [$7400 
RAM #4 #3 | #2 





$7COO |$30N0~-SHIFF 
aX SCREEN LISPLAY 


fo a a le eet 





This machine-code (I've omitted the initialisation routine to direct the ! RQ vector to 
$0278) fits the bill. Et stoces the addresses ‘from and ‘to' in the random-number area 
in the zero-page. 

iHoldes key byte 0,1,2,... 


G27a 00 BRK 
i LOA $9274 load key byte 
osse t My Ms BEQ g5A9 Exit if it‘e zero 
OaEt on ay iKoy byte now 4,8,12,... 
28 m On FSFE Flip blta... 
Upae 43 af eee : 41 for 2's complement 
G245 69 BS ADC #580 Gives #80 qiaus 44¥crean# 
G2u7 Ao Bo STA ee sHigh byte of start uddress 
5 Tut 
ug A 0G LDA wae ;tnitialiae offset Y 
Q2He KS AB STA pee io zero 
O2BE 45 ¢ ST SA set low bytes 
1395 4 aN Ue era PULTA Aad react key byte off. 
7 7 | ayat! 5 
cae He a ae Ve jNow (BA) S7COO mtc;, (4A) *h000 
247 AD Oh Lbk #194 Counter far & pag 
O28 4 HA 4 .Tranafer Joop for 1 rage 


Oe ia 

O29 ba FY 
WIA EA BY 
Uk f Ba RY 
Head acy 

Uday Da Fo ; 14 
OWA? Ge 2h EL int ae 





sCoueinus interrupt. {FAZK BASIC 2) 


SU cm oe ane ae ree ah ee a ec 
FN ene TELE R  S RI Q P TR eeg aoe EMLTWEE ome Srge monge S Atat a sree 







pcb vic era Je sind et cil asi ail 
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0274 OO AD 7A 02 

Q202 49 FE 38 49 80 85 89 Ad 

624A OO AR BA BS 

G292 02 AY EO BS 83 

O29A 88 9! BA SS DO FOE 

0247 £6 64 CA OO £2 4C(Te_ eh BASIC 4 5 SS EA, 


fest the routine by displaying the registers from monitor (type .R} and changing IRQ 
to 027K. Enter .G 0004, which substitues the new IRQ for the oid. if 027A did not 
hold zero, the screen will iramediately FU with some lower part of RAM, 

The appenrance of this type of auimotion can be improved with a form of tin- 
betweening'. A serven Is not simply moved bodily in one movement. Instead, each 
sercen replaces its predecessor in two stages. ‘Lhe first compares the two screens, and 
puts blanks in all locations which are not identical. Then it shifts the new screen. The 
effect is to simulate movement move accurately, by keeping the fixed parts of the image 
but temporarily deleting the moving parts. Thus part A does not instantly reappear in 
position B, but only after a very short delay, This is worth trying, although with 
some images which rely on reversed graphics there may be too much flickering. 





Table of screen memory focations 





Screen line | Start of line 


“number | 40 columns | —-—«80 columns ~ 














o $4000 32783 $000 32748 
t $4928 32508 $8050 32848 
2 $3950 32848 sa0a0 22928 
3 $507B 32888 | $ROFO 33008 
4 $B0A9 32928 ! $8140 23088 
5 $80cKy 32968 ! $8190 33168 
6 ' $80FO 33008 { $A1EO 33248 
7 gaia 39013 $8230 33328 
a $8140 33098 $82R0 323108 
r) $4168 33128 $A2N0 633458 
10 £8190 33168 $8320 33568 
li | $81u8 32208 I $8370 33648 
12 | $atea ga24e $63C0 33726 
13 | gazon 
14 $8230 
15 | $4258 
18 $8280 
7 $R2A6 
1B 99200 
19 $82¥8 
20 86126 
21 $8348 
22 $8470 
a3 $83C0 
24 $8IFK 








9.6 Pen Plotters. Plotters are not common poripherals: they are used for compuler- 
aided design, #nd are not often found in the micro world, The best plotters are large 
pleces of equipment, either ‘flat-bed'ar ‘retary; the latter ase wlde colls of prpar. 
Benson is one manufacturer of thin type of equipment; Caleomp Is unother, Samller 
senle plotters ara available fram, for example, Hewlett Packard aed Heuston Inateu 
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ment make smaller models, desk-top size. The principle of these machines is te attach 
a pen to a catricr which is movab!s in perpendicular directions under program control, 
Typicnlly, two stepper-motors drive the carrier. An ‘unintelligent’ plotter can move its 
pen only i sicps; ‘inteHigent' plotters can ‘home! and store coordinate positions, They 
may have other features, such as a set of alphanumeric character plotting routines in 
ROM. The precision of the motors controls, to some extent, the maximum plotting-speed 
obtainatle. And the step-size controls the fineness of the resulting drawings, which, 
because of the stepwise nature of the plotting process, inevitably have a slightly 
serrated appearance. Typically, several step~size and step-rate combinations can be 
selected. For example, a small Houston ‘HiPlot' can plot either 210 steps per second at 
-01 inch step-size, or 480 steps per second at .005 inch step-size. Thus the fastest 
rate of drawing is about 24 inches with this mode, This parameter is rather itiportant: 
a compliented drawing can take a lot of time. Moreover, the baud rate ig also import- 
ant. Suppose a CBM has en interface set at 600 baud; this m2zans 600 bits (not byte.) 
per second. If the programming system is such that one byte generates one movenent 
of a moter, then & maximum of only about? 75 bytes can be sent per second; this is 
fine for (say) a daisywheel printer, but confines a plotter to perhaps an inch per 
second at most. 

To illustrate the programming methods used with plotters, [li take the ‘Hipiot’ 
as an example. This machine is cuntroNed by only ten commands; & of these are 
directions 1 shown in the diagram. and the remaining two commands move the pen 
down to the paper and Hit it from the paper. All other positioning, for example of the 
pen before plotling starts, is dune manually. Each direction on the diagram is lebulled 
with the chnracter which, when sent from the computer, causes one step to be plotted 
in that direction. Odviously, each motar can step in the positive direction, or in the 
negative direction, or not at all. Thus there are 3*3=9 combinations. There is no 
Particular cunmand for no-movemcnt-at-all. 


w\ p /Q 
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The 45? lines are of course gencreted by simultaneously activating both motors. This 
is useful, becuuse some of ne jaggedness of lines can be taken out, When plotting a 
Straight line, for example, the appearance can be improved by building it from 45° 
lines with either horizontal or vertical lines, rather than drawing it only wits lines 
parailcl to the x- and y- axes. The dingrams shew the difference. The progrua on the 
Next poge druws the best straight line between two points in this way. Note Unat it 
uses the notation NW$, £$, SES, end so on as a ruther obvious mnemonic. These 
Strings have tu be initialised elsewhure in the program, by 


1000 age! P' eZe"R": sha°T ew $0'V" ne $e"Q"  acg="8" raw$s" UO"  nw$s Wags aO Yh dhe" Z" 


Lines 197 und 109 test the gradient of the line which Is te be drawn; (hose with prad- 
jent < Lare drawn by program lines L1@- 195, and steeper steeper straight lites are 
dealt with by the part of the program starting at 300. Note that strep Lines require 
N$ or S$, while gentle lines use WS ae R$. Logical file #4 is asaumed to be apen to 
the plotter. 

Cireley can be difficult te proyram, The standard algorithm, which wes the 
Tinimun: of trizanometeleal eateuishan, fa: 


200 PEM QeURGHRES GLNTENDED BY HACH STRAIGHT-ELNE SEGMENT, EG Qr10 PLITS A 
OO-SiREO FIGUHF 

S10 G-R: HO) REM ASAWIOB, © ASH H ARB INTERMEDIATR VALUES 

$20 N-300/Q > [eM ON NUMHEH OF STPES NUMBER GF RRUETITIONS OF CODE 

SIF COBCQ* (PE 6280). be SPR CQe PRL pe 1a) REY TRIG PARAYETERS 

S19 PON J. oO THT 

So CG*E-Hes: AwG|EsHOR REM THESE ARE THE X- AND Y-GUOKDINATES OF THE NEAT PC. 

260 RUM DAW THe STRAIGHT LISP SEGMENT TO THE POINT SoC, fed 

Sv Gee Li-a 

She REMY J Bee " webs 

In brad tlee, } byte way be trenamib iad wlth 10 Gite favy)) Rence the vagueness. 
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GF REM REHM EER EERE REE EH ERR RE ERE EEE EE RH 
LUO FM te SUEMOUTINE TO CLOT LINE BECHEEN SOUNTSe GIVEN & AND Y¥ DISTANCES 
102 AEM PPCCRTCOPESETTOTCOT OCC CCE CESSES Cee er eee eS ee 
10S xvas YF -9 

yO4 IF X0=20 THEN M=1E9: GOTO 300 

107 MrARS(YD/XD) 

109 IF M}1 THEN 300 

110 IF XD)O THEN X€<E%: YS=NES: TF YOCO THEN YS=SE$ 

120 LF XDCO THEN AXGsWS: YSoNWS: IF YIRCO THEN ¥S*SWS 

130 XO2ARS(XO)s YOFAHS(YD) 

160 FGM Sel TO ati; PRINTE4: Xt 

170 IF M#S>¥P THEN PRINTES+Y$: YR=¥P+1: S#f+is 
1&0 NEXT 

190 FOR JsO TO 1E5: IF YP-1¢YD THEN PRINTR4s¢8%: YPS¥P+l1 NEXT 
195 RETURN 

200 IF YOO THEN ¥S=NB: XS*NES: EF XO(O THEN X#2NHS 

J07 IF ¥G=(O THEN ¥$=S6: XS=SESe IF xX0K0 THEN X$=SWE 

B04 MITABS(XD): YERrASSCYD> 

305 FOR Set TG v0: PRINTE4, ¥% 

310 IF SOMeXE THEN PRINTE4+X6: XP2XF el: S=Sel+ IF S¢Y GOTO 316 
320 NEXT 

930 Fuk J = 0 TO LES: IF xP-1¢0XD THEN PRINTES)+X$: XP=XP¢i: NEXT 
340 FE TUAN 


IF S¢xD GOTO 170 


Pattern plotting Mathematical curves and drawings, either as single tong lines 
(e.g. Lissafou figures - see 'SET'} or as repeated plots (straight line segments mimic - 
ing string and nails/ repetitive drawings in which parsmeters are slightly varied/ etc.) 
have been fairly populer. They may also be useful in mathematical education, Curves 

with plottable formutas include these following examples. These equitions ere all para- 
metric, so pairs of values are generated, and can be plotted immediately. The scale of 


course has to be adjusted so the crawity is aptly sized, 


Cardloid: x«2cuosa + cosZa 
ye2eina + gin2a 


Triacctrix: xecosa + cos2a 
yraina + #inza 


Cystlold: x=a + aina 
y=l - ncosa 


Folium: x+t/¢(i+t?) 
yett/(l+c?) 


Eptcyciold: u=mbeosa - bcosma Btrophoid: xe(t?-1)/(t?41) 
y=mbsina - bslnama yet (t?-1)/(b%41) 


There are of course innumerable equations of functions of y in terms of x, whkch are 
instructive to plot; for exainple: 


-(x-a}? 


Catenary: yee comhi{x/e) Normal: y-e Damped sine: yoo" (Asiowx + Bcoswx) 


The specimen below, and that at the foot of the page before last, were con- 
structed by a different principle; four separste types of ‘tile’, used aa bullding-blocks 
and drawn next to each other in randum sequences chosen by the computer, make up 


SERS 
BNA 
COT 


NR 














br 
UNAS 
HE \ > 
a Wel 
RITZ 64 
To Pay 


OP ITP I 
Va ; 
FE GUN 






Wy 
MI OUD NR 


DOT IT Het eerie cn, A Oe REE ME mR nS oat RNR IMME Tae PNAS SE er MMR Rr od 


Sid ae AV A Scalise etek Sable lt cee an 
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the entire drawing. This example plots ‘tiles’ of these designs; when drawn as neigh- 
bours, their lines must always link, forming an Islamic-style ebutract pattern. 


NE 
a GC 44] 
The program is too tong for reproduction here; it has four subroutines, one for each 


‘tite!, and a routine to conyert the random sequence of five or 30 ‘tiles' into & sym- 
wetrical array. The actuat loop which performs the plot is this: 


3500 REM #¥*2 NOW PLOT SYMMETRICAL PATTERN USING CAK(,) ARRAY DATA #*# 
3510 ¥V = 1 :REM ‘LNOP’ 

3520 FOR H = 1 TO 2eHAIZ 

Q890 Un CASCH IY) GTIUA 100) 2001 3001 400 

3540 NEXT H 

3550 VeVel: LF Vi2sVERT THEN END 

3540 FRINTES, Pus: FOR J=i TO 3#5: PRIMTE4+SWS: NEXT 

3570 FOR J21 TO 3¥S#(2eHRIZ-1); FRINTE4+H8? NEXT 

3880 GOTO 3520 


Lines 3560-3570 move the pen back from the end of one line of tiles to the start of the 
next. : 
Three dimensional drawings. Perspective drawings are possible, but the pro- 
grams are mathematicaily difficult. Each corner has to be ertered as three co-ordinates 
and their positions on plotting calculated so that the geometrical shape is projected on 
a plane, The picture of a CBM below was plotted like tris; in fact it is a stereo plot, 
the originat being a stereoscopic paix in red and blue, When viewed through two 
fiiters, red for one eye and blue the other, tis ercates a stereo image. Several bluck 
and white films have bren made using this colour sepaistion technique. Again, the 
Program is tow Inng for reproduction. Readers interested in this will need to consult 
textbooks on the theory of perspective projections, matrix arithmetic is usually the 
preferred way tu store duta and process it. There are some snays: one is the hidden- 
line removal problem, which tries to deal with lines which would be blocked out by an 
Opague object, but which the computer may nat recognise as unwanted. (The CBM 
picture had nu ‘corners’ input of its far side, which evaded the difficulty). Another 
snag may involve the conceptual framework of the projection: the arithmetic may 





Qesume that the object is fixed, end the viewpoint moves around it; or the object it- 
self may be rotated. if the method Ixn't suited to your needs, you may find it necess- 
ary to calculate angles and distances in order to make the image the correct size or 
make a series of images bear the correct relationships to each other. 
Pseude-perspective drawings - axonometric or isometric - are easier Dacnuse 
there Is much legs calculation Involved. As an example, consider what is required to 








Isomatric 


plot a@ mathomatical fenetion In I-dhoenslons, The aim jx to plot a function ta produce 

7 an knage of the surk indicated in tha: nketoh . 
ow ean this be cane? The simplest method ts 
to dynere the hidden Hnhe probbun, simply 
plotting eross rections of the curve fewan deft 
ta right for a ristiyer of values. Taking account 
of Kidden fines muies the programing, tid 
the running Une, longer, The ensy propgrusmuting 





weasmceret chia phere TT te ee 
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solution is to adopt a modified axonometric 


Projection, exactly like this diagram except 
that the horizontal y-axis is drawn to coin- af 
cide with the z-axis, Now, for exch point <a 


Xp, @ set of values z(»,y) are found, and Az (x,y) 





Protted as dots provided thet each value 


A, 





execedsa the previous vulue. In this way 8 
column of dots buitds up, scanning from 
left to right, which takes the form of the 


\\-—. 
type of drawing we have in mind, This method is fine with a YDU, but not very gcod 
with u plotter, because more time is spent moving the pen than actually plotting. So 
4 more elaborate method must be used, which stores the maximum value plotted so far 
at every x), and plots @ continuous line from left to right, except where it is inter- 


tupted Sy some larger vaiue. ‘ 
FOR ¥ = ¥2 TO ¥2 STEP YS 
FOR X = X1 TO X2 STEP XS :REM XS,Y¥S NEANS X-STEP SIZE, Y-STEP SIZE 
2 © FNC(X,Y} + ¥ :REM EXTRA Y GIVES 'PERSPECTIVE', INCREASING THE 
"HEICHY' OF FAR POINTS 
‘REM NTH COL. OF PLOT, N=0,1,2,.,. 
‘REM DON'T PLOT SEGMENT IF VALUE < MAXIMUM 
| 
f 
$ 
i 
é 


:REM SAVE KEW FAXIMUM AND PLOT 


N= (X-EL)/XS8 

TF Z¢MAX(N) COTO Li 

MAX(N)=2: PLOT SEGNENT 
Li NEXT X: NEXT Y 


This schematic BASIC program shows the method. 
3.7 Sounds and the PET/CAM 


Introduction Computer synthesized music has achieved considerable success, notably 
with organ-like sounds and special effects; ordinary orchestral instruments remain 
resistant to synthesis, bevsuse of the extremely complicated waveforms which they 
gonerate, Before considering microcomputer music, let's look at a typical note-synthes- 
ising method, We may distinguish three stages in the life of a note: attack, sustain, 
and decay. The attack - the period in which the note is becoming established ~ has a 
spiky and irrcgular waveform because of the note's instability. This part is difficult 
to synthesize. The sustained part of the note has a steady waveform, ineluding 
harmonics characteristic of the instrument. Finully, the decay also has the sumu wave- 
ferm, but harmonics tend to disappear as the note attenuates, 


Attack Sustain Decay 


To simulate these stages, we can hold a table of, say, 256 bytes per note. Each byte 
May have a vulue of 0-255; and all the bytes together provide samples of the wave- 
forin from the aturt of a wave lo its end (i.e. 1 wavelength). If we eycle through the 


‘attack’ table a number of times, then the ‘sustain’ table, and finally the 'deaay', the 
entire note [s simulated In this manner; 


ALALAAT AAA Pe eee 


Start <—'At tack -—> 4—— Sustain ---—~- 





—3—ee Gem Peony ——-4 


If the digital values generated are converted to annlogue sienate by a afgital-te- anal- 
ogue converter (DAC'), ab approximation to the original souned will regult, 
fh aynthealzed from a vocel cord analogue (hunzing sound) with perhaps 2 bandpasa 
fitora for each of the major formants of Apeceh sounds, Chips are availstte, ond are 
used commercially in sone products, lo produce sounds of 
ey, and envelopes shape, lo synthesize speceh, and an on. 
New, 12 ineh serena CMs are all equipped with an teaternal apenker of sary 
Jow volume). ‘This provides, aa we'll fee, an essy way lo generate tones, cllcka, 
squeaks, and aa on; it relied on a square wave, brietuced, in the CUM'n cnse, by the 
ahltt reylster, which periodieslly shifts a bie ty be aapiified by the speaker, ‘Thin haa 


only (vo poxttions, out and in, so the suund Ia ceuster than thet produced by digital 
to analogue conversion, 


Speech 


pecified wavefurm, Teequen- 


. 


2a SATE nS OP, et NT 8, TCE a A ae A ee RT A RS Yr tnt, te ALN RR Teta mgt we Fe 
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The frequency produced by these methods can be calculate’ rams eta hes adler 
articular case, but what is the corresponding note? Several MUSIC? Se ae 
im ludi the sefentific (‘Just’) scale with middle C of 236 Hz, und two equa ee 
ato ste scales, of which the Anerican standard has middle C of HOLS Gd aoa e — 
Tntersutonel standard a middie C of 248.65. Chromatic seales have ff ee ee ine 
octave repeats, and their frequencies have a constant dal Si Sa (1.05946...}- 
abridged summary of the full range of notes fur each seale iotlows: 


PERED CHROMATIC SCALE ISCIRNTIFIC SCALE 




















NOVE bree GY: ASA [INTERNATIONAL PrTcH] _— 
cq | sees | 258.65 r 258 
\ Ch 277.18 | 274.92 | 
D4 293.66 | 290.33 238 
Deq g11.13} 307.59 
Bq 329.63 325.55 320 
¥4 349.23 315.26 341.33 
Fe, ; 369.99 { 365.79 at 
Cy 392.00 ; 387,54 384 
| GK, 415.30 | 410.59 MG: 
| Ag Quo | 435 426. 
Avg 465.16 460.87 oe 
| Bg 493.88 | 488.27 ‘| a 





ilal Chambertin is one of the most weli-known authorities 


POUNGS: mItt Tiler Neon PMet Sopt.’77, or his mare recent book, ™EUS— 


si eneration by computer; sce Byte, Sep more ena 
oat “Applets ef wiiehopreddaseee! (Hayden i Wiley). both sac Be cand 
the PET appenrr to have originated from him, tA commercial produc bi ry hos stele 
synthesis by MIU, is his. Another well-known product is the isa bat ay 
or VMM, by AB Couputers. Each has software with a digital“ranunns cae a reAkest 
VIC nas uw d-voice syntnecizer built in. Other machines, a dats hot a ae 
built iu ag standard, As we'll see, the usual Pei system uses 3 oe Aa tes 
operation which ig probably easier to work. Let ac (lest inet A oe rae tba ar 
on the PET, using extra hardware. The programming is ar ica 
screen models, which have the same circuitry ready supplied. 


Square-wave generation with the VIA's shift register Before the cee ere 
here are throc alternative methods to make the VIA's square waves: aren Sy ee 
arran ed in order of cise of implementation. { don't recommend cere sie be ee 
ex sarees to try this, and can’t accept responsibility for disasters whk ¥ 

(Not that anything untoward is likely to huppen, in fact). 


(i) It's not widely Known that the PETs sound can be ee ine on 
connections at all, except ane to the M pin, corresponding to : pbalrcie’ ie TURE 
moyt-but-one pin on the underside of the user port. (This por ee pares 
port - cheek an the menual), If a single connection to this pin ty vai behest ais ae 
a radic, its radio frequenry signals will Le picked up, and ry ne 
result iy rather poiy, in the iad Mien tno Oe aa sane tal, oe 

j Y game single wire can be ache ? 
ing ‘ils Re searha nn connect the output to A or B, enabling the volume control 


ta operate. (Mot C, which doesn't). o> 


Ao ° op 
; ‘ mill spenker, glves 
(iii) A simple utnysifler circuit, of three components plus ao eS 
very adequate sound. The cirentt diagcan shovts how thes Sa aan ran eek hey me 
no xketeh ou the faduwing page shown haw they uppeur, Raise Ae poh ea 
computer, Ob ds of courne punsible to buy nopilfiers as chips, whic x 
and compet anita aveallabie. +o 
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a 
fj 70 8 {typical} 
Be Od £2 
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The signal may be reduce. by increasing the smaller resistance from 105 ohms. The 
larger resistor's value is set at 34000 ohms since the gain is of the order of 200, s0 
200 x (100 + 70) = 34000. 










ca 5st Parse 
rece Vie PT IEEE 


aia esctee 






BIOS trnaisfor, 


Programming the spenker is a fairly easy mutter. The usual method is to use the VIA's 
Shift Register, at {E84A. A shift register moves one byte to the right at rejrular time 
intervals determined by a clock. In our case, the location SE848, which is the low byte 
of timer 2, controis the rate of shifting, Also, the Auxiliary Control Register, which 
has & alternative shift-register settings, is set for ‘Free Kunning Output Mode’. Let's 
first look at a machine-coce example, in fact the routine which BASIC 4 uses to tinkle 
its internal bell, 

The jump-table addross (EO?A in the $032) causes the chimes to ring once: the 
jump is to E6A7. To ring the bell twice, call E6A4, which has the command JSR EBAT, 
and consequently tinkles the bell, then drops through to tinkic if again. The bdell- 
ringing routine is like this: 

LDA #$10 

STA $E44B ;AUK,CTRL.REG. ¢’ACR') INTO FREE SUNNING OUTPLT MODE, T2 CONTROLLED 

LDA #S$OF 

STA $EA44A ;SHIFT REGISTER HOLDS 0000 1121 
IQOOP LDA «xxx ;LOAD A WITH SOME TABLED VALUE 

STA $2948 ; PUT A INTO TIMER 2 (LOW) 


EXiT LDA #$00 
STA $EHW4A ;SHIFT RECISTFR HOLDS 0000 o0c0 
STA $EB4B 7ACR HOLDS 0000 6000 


The values the CBM loads are OF/ iE/ 3E/ 7i/ 3e/ 1Ef DE in turn. Tha delays before 
shifting are ln proportion to 1:2:4:9:4:2:1 (i.e. spanning 3 octaves, because the fre- 
quencies are tialyed by the delay's doubling). The rationale is thig: 

(1) Bits 2,3, and 4 hetwean them control the shift register; if for exampic they 
held 6090, no shifting oceurs; Ml cuuses Just 8 bits, the present contents of the sift 
rgister, to be shifted under control of T2; and - our sauad generator - LOG ceuses 
the shift register to shift In'irea run’ output under the centrol of TZ. Thls means that 
T?, which ts decremented at every clock cycle, cnuses 1 bit of the shift register to be 
output when ever T2 bocomea zero, T2 is automatically relonded i this mode; so fa 
the shift register, ACR fa ERd4 (59167). 

(il) T2 hua a blygh byte and o low oyla. Au wo shall aee, only the low byte In 
ugually used for tone generation. [te locutian la EAR (-59464), 

{U4) The shift regtater itself is e344 (259406). Hla pattern of blta detcrulacs 
the frequency of tho nals and its timbre, 

To ate how thease three VIA rugleters cnuac A aquare waye to te generdtad, 

a PPE errr wa consider these UWustrationa of Ibe ahlft reylal- 
oe hoitaor 3 er at reguine intervals as T2 Unies out. Able 
eue (H1G1 (OO) Came Lo 1 rarrien ' -_ thy ; t 
T2 our; {O01D1700] Chast” 1 ee BRC viior tow (lor 9) on ChZ at cach a 
T2 out: {500101101 Cba<0, FY these intervals, and tha rusuttlng: wave Crain 
72 out; (HO0010) I] Ca20- sf ot appears aa shown; Ut has oniy twa aaplitucaun, 
72 out: (0606 ,6L] tae le and la a square wove (with dinturbancnd dep- 
: : a ae ending om mechanioa and elotrliest srrery, 
Moony uf those wave traing corresponding to SR'a bit patterns mound bdenticns ta waves 
oriyhiating from other bit patterns which at first sight appear diffareit, Fur axampoe, 
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Ot (0000 0001) and $80 (128 decimal}. 1000 0000 sound identical, because each produces 
a single pulsc. More subly, SOF = %0000 1111, changes the note's apparent frequency 
because the ear picks up the period of the wave a5 hall that of, say, 1110 1109. This 
applies also to GO11 GuU1i and 0101 0101 and their variants, in which the frequency 
shifts (of an octave each) are cuused by the repetitive bit pattern. Note aiso that — 
patterns which we might cull 'inversions' - ¢.4- t111 1000 and 0000 0111 - seund alike 
to the ear: this ia a fact about the psychulogy of perception, rather then physics. we 
can list all the fundamentally different bit patterns; they ure 


ZESULTS OF m ZiMMeRMANN’S “MUSIC GENLRATOR’ FROGRAM (FES &t BYTE! 


oa obo oooodd 
30000090 01 ¢ 
,oOoa0 O43 od 
F7eeorooaotrlds 
yuvoH g1 08) 
om aoeLltgaiaid 
mo Oo LIL 
weonmor1ooud 
Fuoedteaszt 
Theo odiurtor 
“3 OO tc 1 O21 12 
pry nooor igi 
7woaizrbrovoirtod 
4300104 G1 
aS ogor,er1yod 
51remsLogoit 
asSoiecgtroyod 


Zimmerwen's ‘Byte! article also includes Fourier Analysis methods. routines being given 
c PET.* : 
= ek advantage of this method of tore generation is that, once started, it 
continues. Apple's system requires the machine to continually tweak the speaker, So 
no other processing can be carried on, To show how this can be used, the folowing 
shart machine-code program uses the interrupt to help play a tune. {It is written for 
BASIC 2. other BAS{Cs need thelr correct IRQ in place of EsQ2E). The overhead in 
terms of time ts tiny; the space overhead depends on the taule of notes. This example 
‘plays' the zeru-page, producing 1 note with each interrupt: you should therefore be 
able to hear repetition of the ‘tune’ eavh 4 seconds cr so. Load the routine, and point 
the [RQ to $0300 (e.g. SYS 4/ M 0090 0O O03 -- same --}. The routine ix now active, 


Program Demonstrattog use of the Intorruyt to Play « Tune sitio BASIC rung. 


NO. DEC. BEX DUMP DISASSEMBLY 

768 £6.00 $0399 INC $00; LOCATION $CU TS A COUNTER; EACH TIME {T IS 
2 «90 F003. ~—«89302-«KEQ $0207 | INCREMENTED TO FOO, THE NOTE 15 CHANGED. 

bE Gh SMe $EA2E Meer 
Seen ie ae eae) LOA #SPF ; RELOAD THE COUNTER (SMALL VALUE = SLOWER) 
5 777 85.00 $9309 STA $70 ; : peer 
; 5 OUR DPMONSTRATION PICKS ITS NOTES FROM TH 

Cease aoa twe gosoc + ZERO PAGE, CYCLING THROUGH 256 VALUES. 
8 yea BD 48 HR $0315 STA SEBSE 3 STCRE ACCUMILATOR IN THE TIMER. 
9 «787. WC QE KG $0313 UMP $2628 ¢ AND CONTINUE NORMAL INTERRUPT. 


POKER 59467, 16 niarta SR snifting in free-running mode. This storts the ‘tunag', POKE 
59466, enters » byte fied may be needed to anke the tune audible! }. lt ales controls 
the Umbra of the notes produced, within the restrictlons linpased by the square waive, 
A BASIC program can Le run walie the noise continuea, (POKE 59467,0 to turn it eff. 
"These dre fairly easy to convert to blher ROM ante; ate Chapter 1%. Fourier was a 
French muthamatician whe proved that any perledtic wavefora could be peneraled by atding 
bing curvau together (sumetiang - ae with aqnare wayvae = infinitely many In nusber), 
Tuntamantedea! end ‘overtones’ ste an aepecl of thia, The proceam es gsimitear to that 
of Prolemy, who in effect aynthesined ellipaea from maty circular wotlens, 


i perigee rm he aes meee me ek mm me te 


Ce were oo mas ee 
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POKF 776,X veries the rate at which notes are changed; this location is used to count 
interrupls; the smaller the value, the longer is each note plryed, up to a maximum of 
4 or 5 seconds. Obviously, a table of bytcs can be played, so a recognissbie tune will 
emerge, while BASIC runs, A toble of 256 bytes (say) played at the rate of 2 notes 
per second (the equivalent of POKER 776,25 or so in aur example) will run for 2 minutes 
before repeating. We can use our technique of ‘switching’, i.e. using a special POKE 
Incation to cause the interrupt to choose different tunes, from tables of perhaps 4 or 
5, In fuct, these could be chosen by the progrem; thus, @ gre program might be 
accompanied by music of the appropriate mood, like 4 pinno accompaniment to a silent 
film. 

This domonstralion BASIC program plays 2 octaves: 


92 REM FFRAFE SHRED ER EEOHIF IRE TRR CEE TE CAPES RAE E REET TRE ERA RAZ ETRE TERRE EEE EE 
J REM # = DEAMORSTRATION OF CHAOMATIC SUALE OF 2+ OCTAYE RANGE ? 
94 REM € GACH NOTE OSTALNARLE BY A SINCLE “POKE” FROM BASIC OR MACHENE-CODE # 
OS REM PREFEPHCA OGRE RF ETI OR AOEEAR SPER EERE EL AA PE REA ERES ERR EROE TERE REESE ER TE ER 


96 REY f 

97 RFA 

100 FOKE 59467, 16: REM FREE RUN MIDE 

110 POKE 5946a,0 : BEM SWITCK OFF IF CONTENTS EXIST 

120 POKE 59466, 22; REM OTHER VALUES WILL PROOUCE THETR OWN TIMBRES/ TONES 

130 DIM #(30) : REM ARRAY WHICH WELL HOLD THE CONTENTS OF DATA 

140 FOR X = 1 TO LO00O: READ N(X): IF N(X) <> 999 THEN NEXT: 

I5QON@=%~ 1: 

191 REM 

192 RE 

E93 KOM CRAMP EPR ERASERS TAR SELORLE IANS EC EAE IPAS ARIE RAMEE RECT ESC I RRR A ERA AS EAE 

194 BEM # PLAY ALL THE NOTES FROM THE DATA TABLE IN ASCENDING SEQUENCE f 

195 REM POPE PEERESI CARRE CRAP AAT ORL ERLE THAT ERC ASP AREET RESET E LOSES PRETTIEST EF 

196 REM 

200 FUR X «= L TO W: 

210 POKE 59464, N(X): 

220 FOR J = 9 TO 200: NEXT J: 

236 NEXT X 

500 POKY 59467,0: END: 

OSL KEM 

992 RIM 

997 REM FEGEHPRSERFOR FERS RSAERAET EG RPEP EAR ERAREAEOREEREE ES CASS STENT CRC OL ITEC EF 

994 Rem # STARTING VALUH OF 252.1 FOUKD BY TEJAL ITO GEVE CLOGZ APPROXIMATIONS # 

995 REM # TO TRUE COKRECT CHRUMATIC RATIOS; BUT DORS NOT HAVE PRRFECT PLICH. & 

996 KEM J START VALUE MULTIPLLED BY 2 7 UNS-THELFTH; THEN 2 CYCLES SUSTRACTFD-# 

Hy pe SPCHORECESOROOHELRE DEERME SCER LAG LTE SADIE EPSSSEARROATAL IR ZASO ERS EL INSETS 

1000 DATA 250, 236,223,210, 198, 187,176, 166, £57, 148,139,132 :RPM PIRST SBT OF 12 

1010 PATA 174,117,110, 104,98, 92,87,22,77, 73,69, 65 

1020 DATA 63,999 
| 
t 


REM READ DATA IN. 
REM N LS THE NUMBES Of ITEMS IN THR TabLE OF HOTES 


REM PLAY ALT. ROTES 
REM POKE TIMER WITH DATA 
RE&M DELAY LOOP BETWEEN NOTES 


REM SWITCH OFY 


REM SECOND SET OF 12 
tREM 999 SLCNALS ENO 


How can we calcuiate the absolute frequency of a note? Let's say that timer 2 contalis 
the value T (<256). The timer decrements once every microsecond, 30 one bit will shift 
avery T mieroseconds.* So @ bits are sent in 8T microseconds, and the full peried of 
& wave is twiee this, assuming a pattern like 0600 bO0L, not un internally repestiog 
ou: such as OLML 0101; so the frequency is LG00000/26T cycles per sec. This is the 
same an 2500/1. So a frequency of 256 is obtained by poking 214 into T2, When gen- 
erating squate waver, the greutest precision can be got by using the langest pu:sitle 
vulue of T2; this menne ua correspondlogly fast square-wave, O10! 0101, This has 4 
limes [be frequency of 0000 If1!. Thner 29 high byte (in Esa). 99465) moy need to 
be used as well an its low byte. 

Several square waver can be ponerited sinulumeousty although the resetuthart 
In Inevitably poor: this requires the reluading af the shl(t register after cach Uder 
tountiown, with the next in the sequence of combined waveforms. The Uming could be 
carried oul by enabling 12's interrupt, bul the techreiur bo tetuny. 


“Tie xecmm © resnonable absurption. R Zuuw (74802 Applications Hook’) tmpisoa that 
the half-period ta M+l.78, aade up of au average fram M+? Ctep of guian). and 42.5 
fSettam af pulaajy. Mie method given esltuntiy diftfarent veiuea for the conchantan: $¢ 
wad eed dso tha BASIC progecm above - seu ling wht, AC the cine of writing f haven't 
found « definitive answer to this simple qurestan, 


OR I Sa a pre ee RR RE FEF PR ERS epee al ng ASR Re ee 
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These short EASIC routines demonstrate typical easily-achicved sound effects: 


(1) Giiseande 
1000 POKE £9466,15: POKE 59447,15: REM RECULAR SQUARE WAVE + SK ON 


1010 FOR J = 255 TO 1 STEP -1 > PEM LOW TO HIGH PITCH 
1020 POXE 59424,J : REM BRIEFLY PRODUCE TONE 
1030 NEXT: PORE 54467,0 : REM SR GOFF WHEN LOOP ENDS 
(11) Beep 
1000 POKE 59466,15; POKE $9467, 16: REM OR USE DIxFERENT (¢215) TIMBRE... 
1010 PORE 59461, 140 : REM... OR TONE ; 
2020 FOR J = 0 TO 20: NEXT : REM SHORT DELAY LOOP 
1030 POKE 59467,0 : REN SWITCH OFF AFTER BEEP 


(itt} Murmur 


1000 POKE 59466,45: F=50454 
1010 FOR J = 1 Tu 200 


1020 X=RNP(1) 416 . + REM ACTES VARY AROUND THIS 
10930 FOR K = 0 TU 8tsND{1 ‘ 
104M PORE FLN(A+E) : REM ASSUMES N() HOLDS TAR!.A OF NOTES 


1050 NEAT B,J: POKE $9457,¢ 
SUYMARY OF CB2 SOUND Y1A LOCATIONS. 
Fe48 59464 Timer 2 (low byte) T2L O=o0ff; otherwise, small means high pitch 
E849 «669465 T2H Only useful for slow timing 


Es4A 659466 Shift Feginter SR Contents drterwine timbre and octave 
ES4B 59467 Auxiliary Control ACR Bits xxxxxxxx control 3R (Free run 100) 





Tones with @&-bit resolution Qutpul port A of the VIA has bits PAQ PAT connected to 
pins C.D,E,F,H.J,K, and L of the user port, (These are on the underside}. The dia- 
gran’ shows w digital-to-arslogue converter which alluaaten weights to exch bit, so that 
the most significant bit L hus twice the effect of pin K, which in turn has twine the 
effect of pin J, and so on, The resistor values chasen are ‘preferred valves’; their 
vatues are only approximately in tie ratio 2 to 1. Greater precision requires the use 
of a adder’ cirenit, corrected fur the LK resister to ground. The diugran inckadns 
only 5 pins, ignoring the least significant 3 bits. whose e(fect, in such a simple cit 
cult, is small. The resister-capaciter arrangement provides some smoothing. Pin M is 
freluded, so CH2 sound is aveiable as well; pin 6. with a resistor, cin be added, $0 
tape loading can be aurally checked. The output should ba amplified by ffor exumple) 
a plug inserted inio a portable radio's DIN socket. A simple transistor circuit isn't 


sa Hele: Tare PARALLEL USER Porn tERE 
DEMONSTRATION PROGRAM 7 7 6 


? . - * a vv . . 2 3 wv 
LDA #FF {CONFIGURE PORT A__ “77 of ll Fl wi cl eal ni man 
STA F343; FOR OUTPLT | * ia "i sa =| “| et | NG 


LL LDA 2000,X foe, Liaw MOCK AK ZK LOCK 
STA ERAT; SEND OUTPUT Sees 
INX % 9 3 
BxE Li an ont {if { 
LDA 90 |; TEST STOP KEY aowkx vd 
chp FEY ; (6260 [N BASICS] ome lb =] 
BNE tJ vee ~ ye 
RTS ,AETURA TO BASIC 


Arruititer 


steht &, 
Ne 


This single dereonsirathen routine Firat configures All 8 bits of port A lor output, then 
toneabedly atores 290 bytes CL page) of bylon duty the output port, This ee pealiteys 
pattern constilites the weyeforni. A ceutine to step th: eutput Is provided, dn thin 
wy 260 sioaregt spenker parartians moda one wivelenuypei af the peed. Por fineh fre: 
tieneles Chis id tug grrent, qb ce auylier bates, 


(OF BRE GN w/COLE] 


rhage 32 bytes, maat le ara, Pwo 
OM mpbis tallow, uote that the starthinys waist at Sue ¢ ADNZ > bs arbiirary, coud other 
Vatuesy, ueh oma fire trepy of FAM, can be used, At ont il asope: with thagday the wavelorin, 





169. FOR Dow MGS TO WbZ NO VOKE Sd: be feb: MANE: ARM CISES HAWTGU WI 
f-G- PUR Soe BEB? TO MAS? PONE J, Vawe LBL ING ED: UeseverPiysdsa: Brvb: REM SEKE 


RO aa ln ee 
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CHAPTER 10: THE TRANSITION TO MACHINE-CODE 


ee tA, 








ad_tntroduction and syne @-bit concepts - 

yhine-code programming can only be learnt by trial and error. by experimenting with 
nple programs to see whet they do, und transferring the results of this learning te 
e's own progratas. This chapter explains the cournection between decimal and hexa- 
scimal notation, and the meaning of ‘bit’, ‘byte’, and other related words. It also has 
cort examples of mechine-cede programming; these are continued and expinded in the 
xt chapter. But the bulk of the present chapter Is concerned with monitors: Not the 
DUs, but software enabling the programmer to get to the 6592 chip, The novice in 
02 machine-code will find some of the detail hard to follow: the problen being that 
achine-codg can be understood only with the help of a monitor, but a monitor cannot 
» understood without knowledge of machine-code. Some of the detail must be skipped 
1 the first reading. Chapter 12 has an alphabetic guide to the 6502, to which refer- 
ice may be made, but again, because of ity comprehensiveness, much will be obscure 
1 the comparative beginner, 

The 6502 microprocessor performs all the processing of the PET/CEM, If is sup- 
emented by chips to control the keyboard, sereen, and other peripherels, and cir- 
litry to perform such functions as the sereen scanning and the contro! of the power 
apply. A crystat-controlled clock determines the speed of operation of the 6502, so 
is possible to calculate the precise time taken by a program.* Each variety of micro- 
rocessor had its own version of ‘innchine-code’ or ‘machine-language’. This is a mop 
: dictionary Cin effect) giving 6 one-to-one translation of the contents of locations 
seessed by the chip to the chip's activity. Each separate machine-code instruction has 
ttle effeet; only the combined effect of millions of instructions ensbles @ computer to 
shieve anything. The 6502 is an 8-bit pronessor. It operates in units of @ bits. A ‘bit’ 
as many people know) is @ ‘binary digit’. Conventionally represented as 0 for off and 
for on, it is the smaflest unit of data. Note that a bit jan't actuoify a 'O' or a ‘i'; it 
>a voltage, interpreted as ‘ofl’ in the range zero volts and up, and ‘on’ in the range 
ve volts down, with the exact range depending on the chip. Most of the 6502's deta 
| stored in RAM or in ROM. If a static charge or voltage spike causes a yoltage ta 
rap from (ssy) 4 volts to 2, the bit will no longer hold its correct vaiue; the data 
ili Be ‘corrupted’. 

A byte is a set of 8 bits wired so that they correspond to a single address. 8 
ins on the 65%2 arc used for data transfer, both into and out of the chip. The indi- 
idual bita are ustully represented as dits number 7 ty 0 in descending order, with 
it 7 the ‘high' and bit 0 the ‘low’ bit. This is consistent with ordinary mathematical 
otation, using stundurd bose 2 (binary) arithmetic, The value of a byte can be any 
steger from 0 to 255; there ere 256 (-285 different possibiiitles. The table Delow, 
amifiar to everyone exposed to 'modern’ mathematics, shows the connection between 
ita and the overall byte value: ONE BYTE: 


BIT NUMBER: 
POWER OF 2: 








WEIGHT?: 
0, for exanple, the decimal equivalent of 0000 9006 = 0, 
OOdt OOO1 = 1, 
G000 0110 = &, 
ALLS $110 = 254, 


he dlyislon of a byte Inte two halves of 4 bits (known, sometimes, as ‘nydbles’ by 
process of prronomnasia) (y another convention: [ofa impeonsible te remember ¢48 Kep- 
yute numerle «ymbols for a byte, so Aexedes sagt notation is widely uned instend, Hach 
oble ji represented by 0-9, A,B LG ILE, or KF. At in hexaitedimol Chex’ far short) 
leans 10 fn decieal, 7H? mowng li, 0. 7FP meta 1S. Pnia bs tho represcetetion uneeed 
ry the CBMs bull in moniter. This notation expruanes a declnant tuader of fl 255 tn 
wo characters at moat, and deckusl numbers up to 65559 6-208) In foue characters ut 
yost, The appendix haa a complete ube of heaadecimal decinar 4 bit caversions, send 


‘Shims wugecets Lhat programe (ealeylations far exzaapie) might be accelorated by the ~ 
yea af a faster clock. 

Metectmnl! (all-Latin ta orlgin) ta momatines recomaended an & Qure gitlafactiory 
rord, maturasiy withact auch #uccuee, 


Lat re pees eee ee 





eR me EIA FR tt eter Be pce TI Fe oe ar meaner te ERE ease 


2 plapta atl? DC ctiaaade FAM la Gee aR Sa Se aida a. hapa eA nwa Te ERT aie 


| 
i 
i 
} 
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a conflated table of vilues multiplied by 256, These may be used to convert 16-bit hex- 
adecimal numbers into decimal and vice-versa. The 6502 is equipped with a l@-bit add- 
ress bus; pins 9-79 ond 22-25 between them carry address duta. This design allows 
956? = 65530 RAM/ KOM acdresses to be used directly, without a system of switching. 
16-bit, @-byte hexadecimal nuwders are rupresented by arn extension of the notation to 


four characters: 
TWO BYTES (16 BITS): 


s ni oe Tan 
1a} is{ 12} ou 10 | o| 8 7 
g9| 8] 7 
| 4 o! 









BIT NUMBER: : 





POWER OF 2: ; 13{ 121 tt 10 
256* POWER: | s{ 4] 3] | | 
WEIGHT: | 32768 116384 j8192 | 4096) 2048 | 1024) 342 | 256 [vas (64 132 [16 





So that, for example, the following conversion relationships hold: 








DOUBLE BYTE HEX _ DECIMAL VALUE 
do00 Ocoo oud VAjY “TT sacd6 FO 
an01 govY Of HIG | -$id00 | 4096 C= 16*256 = 167) 
0000 0100 grud 0901 soot | 1025 (2 44256 ~ 1) 
1010 1011 1100 1101 | SABCD| 439a1 (= ((16*16 + 11)716 + 12) "16 + 13) 
lin dit) 12) 1009 | SEFFB | 65528 (= 65595~7) 





T have used the convention of prefixing a hexadecimal number with '$'. This avoids 
ambiguity in the case of those numbers which happen toa include no atphabetic charac— 
ters. (An alternative convention, unusual with the 502, is to write 'H’ after the Thumb- 
er. This is not always satisfactory: ‘3EACH' can be a hexadecimal number or an ass~ 
embler label). 
At first, thix notation seems odd - it appears strange that $CAFE or $BEEF can 
represent an ordinary number, ang that $20 is 32, and $100 is 256. With practice the 
interconversion becomes frirly easy. at least with sma!l values, which can be converted 
mentally - $42 is clearly 10 sixteons plus 2, i.e, 162; $35 is 5 sixteons plus 5, 83. 
Chapter 4, section 4.3.1 has one-line BASIC interconversion routines which may be use- 
ful. In the absence of a computer or tables, conversions cun be carried out with a cat- 


culator: 
(i) Hexadecimal to deci 


Ll. A four-digit hex numerat (say FGHJ) has weights of 
“to be multiptied by each respective digit's decimal 
value. (This 15 what is meant by 'Base 16’; it is exactly onatoyous to 10:, 10%, 1g, and 1 
weighting the digits of a decimal number). So the resuit is Petal + G¥1G? + H*l6 + d, 
where F,G,H and J are intended as algebraic representations of any value 0- 15. 

It is often cath: to evaluate the result as a continual caleulation, multiplying F by 16, 
adding G, multiptying the result by 16, adding H, multiplying by 16 again, and tastly 
edding J. In this way, the correct weights are automatically assigned. 

(ii) Decimal to hexadecimal, The method is to first divide by $1009, which Is 
4096; this gives Die first, most significuat hex digit, of O- $5. Note this digtt, then 
subtract it from the currently«stored deufmal value, and aultiply by 16. This reveals 
the secund owost sivnifiewnt dijit. Continue until alt four have been found. 

The combination of two bytes inty an address is an important feature of the 6502 
chip, and the fovmuls for a two byte value, which equals 256*the high byte + the low 
byte recurs in mochine-cedea, POKE# and PREKA, ane SYS commands. It is perhaps a 
pity that the 6597 handles double byte numbers essinalng (hat fle fow byte ts stored 
first, followed by the high byte. Io other wards, the order da opposite to what you 
would expect from a norsia) nunmher. (Some other chips. for example the 6409, have 
double-byte addressing in ‘natural’ order). Because of this, pointers used by BASIC 
BASIC are afmost ulways In this furiat, which gan be used without modificatian by tha 


uhip. 









a 





161, 162, {@, and 1 respect 


Two other guneral points about the computer's howdling of hexadecknal arithoretie 
can be mare at this point; ticy are nat enormously important, aid may be skipped 
(iil) Two's eomplowent arithisetic. This is + convention for the representation of 
negative numbers. whiety is isplemenied on the 6502. La its dimplent form, with $ tits 
only, tit 7 Ceterndines the ain af a pudoer: "W' meany posiiive, TP, bit Tovet, menns 
nepitive, Ths rule lo chinge the size ly to flip the bits and add 1. Wha, the Bit 
pattern OLOL VedT ($59 8 decimet) is made negative by ftppiny the bln (tu LO 
DG) and adding 1, to give tH) O11), Nornaliy Uhia counts aa TAT IAT derhinls and 
tia exarple ghewa that a buaser pid Tira two's complement add to gob ar $0100, The 
point da that additive of peodtlye at negative aucbern is gorskilent with nearmnat ure, 
wo that, for fnatnnee, $59 and $h7 add to $100, whlch, fnerlng thy bit which over 
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ows, ig zero, which iz the result required from the addition of two numbers of opp- 
site sign but equal singnitude. Simply flipping the bits does not provide this, as the 
ambers add tu $EF or 255. Note that the canplement of zero ($60 = OCC) 0090) i.e. 
inua zere. does nat exist. For evperienced programmers, there is an exaiwple in 
setion 9.5 which invoivcs subtraction by taking tho two's complement. As we shallsee, 
ranches use two's complement arithmetic ta eateulate the address to jump to; only one 
yte is ellawed for this offset, which therefore hus a maximum value of Qiib 111i = 127 
“the forward diruction, aud 1000 0000 = ~ 128 in the backward direction. 

(iv} The meaning of 'K’, The prefix 'K' or 'Kilo' implies 4 unit of measurement 
ie thousand tines larger than some standard unit. In computer jargon, however, @ 
Hobyte’ is mut a unit of 1000 bytes, but 24 = 1¢24 bytes, a figure which derives 
aturally from the organization of present-dey computers, with on-off stornge. 1024 
yics is not the sane thing as $1009 byles; the hexadecimal interpretation of '1000° is 
$4 = 409S. Not sucprisingly, this can lead to cunfusion. For example, the RAM needed 
» store a high-resolution graphics display aay occupy {shy} $3090 - $AFFF, which is 
vo batches of tength $1009. It is ensy to think that the display occupies 2K, whereas 
1 faet it uses &K. This tadle, of decimal and hex equivalents to integer multiples of 
K, may be hetpful: 





TABLE OF KILOBYTE VALUES 











9716 $2400 | 25K 25600 $6400 
TOK 14240 52800 | 26K 26624 $4300 
WIK 11264 $2000 | 27K 27648 S6C00 
12K (7286 $30GG | 28K 26672 £7000 
$3K 13312 $3400 [| 23K 29696 $7400 | 45K us0e0 $6400 | 61K 62465 SF4c0 
14K 18336 $1809 | 30K 30720 $7896 in6k 47104 $8800 | 62K 63448 SF 809 


15K 18360 $2C00 | 31K 31743 $7C00 | 47K 48128 SBC0O0 | 63K 64512 $FCOO 
64K 65536 $19000 


ote that 32K marks the half-way point for a 64K system, The ET/CBM seceen starts 
jere, ahd getteralty RAN is below this dividing-line, and ROM obove, except in the 
‘ase of RAM on borrds acecased by the memory-expansion ports, and other apeclal 
sea. 


{41K 41984 SA400 | 57K 58368 SE 400 


142K 43093 $Az00 ; 58K 59592 $200 
43K 44932 SACOO / 59K 60416 SECOO 


44K 45956 $B009 | 60K 61440 SFO 


. Ttek 16384 $4000 | 32K 32783 $8000 [YK a9152 $C000 
1024 $0460 | 17K 17ROs $400 33K 33792 $9300 49K 50176 $c 409 
2oug scROO | 18K te432 $4800 | WK 3481s SBBOO | SOK 51200 $C300 
3072 $6CCO | 19K 19456 $4CO0 | 35K 35840 seco | 51x 52224 $C.C00 
4096 $1009 | 20K 20480 $5000 | 26K 36864 $0000 | $2K 53248 SD0GU 
5120 $1409 | 21K 21508 $2490 37K 37588 $9400 [53K 54272 $D490 
6144 $1800 | 22K 22528 $5800 i 38K 39912 §9800 {54K 58296 $Don0 
71GE $IC00 | 23K 23552 $5C00 | 49K 39530 §9C00 | 55K 56320 ¢DC00 
8192 $2000 | 24K 24576 $6060 [40K 49960 SA000 56K $7344 SE000 










0.2 CEM machine-languege monitors ~ TIM and MLM» 


The earliest (HASIC 1) muchines have no machine-coce monitor in ROM: instead, an 
iaembly listing of machtne-code wos provided in the manual fpp. LOAfl). This vecuples 
‘he space of a HASIC program, und in fact evonista of te 8¥5(1939) followed by the 
nonitor, Kuved as 2 single program by extendlag te end-of ASIC pointers to include 
the monitor. (Thr: redundant brackets enclosing 1009 have resurred elsewhere aver 
since). Sinee this machine links a menttar, entering the promeua ia ciffieult - there ia 
ao way to directly key ia the hex inlarmition provaled? A seriea af pokes wil do the 
ick, but there area a great mang, ‘Lhe easiest way fapart fron copyhig vancena else's 
wipe) te to use Oo losderr prog rans like the following, whieh taputs hes tevten, turna 
lhem dato duchanl, und potces the result lotu the correct locations. Hest cee BASIC will 
itn have to be overwritten by poking the values of ther bytea relevant to the moniter 
into place; and, finally, thu end-of-progrum pointer munt Le nlierna to inchude the 
noniter. 

YO IMPUT “ATART ADDRESS"; 8 

ao IBPirr UMYTEN LS 

30 Led POAT «1TOA LEAS (MIDS (LO, 2) 7 Le SLA Lg the (UL 2645 87 NIAT 

40 Put 6b: Beaded: PAINT £,: SOTO 2n 
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TIM (tiny monitor’) has a ‘call entry’ of $040F (=1039}, and a ‘Break entry' point of 
$0427 (21063). The latter works only if ($021R), the pointer from BRK, is set to $0427. 
TIM has simidar features to later monitors, but displays PC SR AC XR YR SP only. 

BASIC 2 machines have 4 built-it) monitor (celled MLM', 'machine-languéfe mone 
itor’; Tather more dignified than 'TIM'). This displays the interrupt reguest address 
(IRQ) in addition to the program counter, status register, A, X, end Y, and the stack 
pointer. It bag a fow slight improves ents; for example. the decimal flag is elenred. 
From BASIC, a SYS call to any location with peek- value zero Causes the monitor ta be 
entered at the break entry point. SYS 1024 (using BaSic’s initial 0) or SYS 4 (using 
a flag which is only set when a program is running) are the favourites. The call entry 
point is $FD11 (=64785), although this is rot often used. 

BASIC 4 has a monitor simiir to BASIC 2. The differences are Ci} it occupies 
different jocutians in RGM; see Chapter 15, starting at D47? in the BASIC 4 column, 
for comparative locations of the subroutines. (ii) The break entry is modificd to abort 
output te printer; the idea is that a BRK always displays the registers on the screen, 
without printing strange information onto & printout or listing. Becnuse of this, the 
call entry point is easiest with a printer: $D472 (254336) is the relevant address, and 
OPEN 128,4: CHD 124;: SYS $4386 a typical series of commands to divert the output to 
a printer. The fie-number, larger than 127, ensures @ carriage-return character is 
accompanird by line-feed. If this feature is unwanted, use a lower file-number (e.g. 4} 
or switch ‘auto-line-feed' off. 








MLM commands The marhine-languaye monitor contains a table of single-byte commands, 
which are checked against the actual fnput. These commands are: > RM GX Land 8. 
in that order. The moitur alse puts 4 period or full-stop at the start of exch linc, the 
sete function of which is to verify that a line is to be considered input into the monitor. 
The syntax and cperation of each command is as follows. (For actual entey addresses 

and other detailed information, see Chapter 18), 

takes 7 parameters ond stores them in & buffer fram $u200 - $0208, 


$0200 PC Hidqh 
$0201 PC Low 
$0202 Flags 

$0203 Accumulato 
$0204 X-Register 
$0205 Y-Register 
$0206 Stack ptr. 
§0207 [RQ High 

$0268 IRQ Low 


; Alter registers 
where they remain until (i) they are altered again, or 
(ii) exit ta BASIC ignores them, or Gil) the command 
G (GO TO os 'GO RUN‘) loads them all into their res- 
pective locations and executes machine-code accordingly. 
Note that mothing happens until G is entered; in this 
way, the altered values are controllable. 











MLM values are input sccording to their wbsahute pos~ 
ition. The following line, for example, inputs the val- 
ues which are underlined, ignoring the others: 
. :21234587890 (2545678901 23456789 [RETURN } 

Po reg SR AC £8 YK SP 


: Alter memory contents inputs a four-character starting address ond eight bytes, 
whieh It stares in the eight memory locations from the startiug address on. 
Like the ptevicua command, the values depend on absolute positions. 
_f Q406 G2 G4 04 GO OA BA G0 00 00 for example puts 3 bytes into KAM, 
where they mmke a BASIC program 10 RUN. Any other values lo the line 
ars sisply ignored. This routine Inecorpyrates a rend-back comparison, so 


thal an attempl to write to ROM or nun-existent RAM gives .? 





R Display registers (ne Parameters) is always caltect on entering the moniter. After 
this, .R kas the sume affret, Thla command js normally a preliminary to 
changing the registers; for instance, BUpP pose the Interrupt veetor is to 
be changed frou BASIC 4's £455 to 6 ruutine at $0274 In the first cassette 
buffer, First, .R dioplays the text Po IRQ) Sk AC RR YR BP owilly 
1) 9005 F485 Je 394 32 92 FA 
pr caiethicue similar, After moving the curser up, 455 is overwritten with 
O2TA, Nethiag happens andl Gy. 0004 entises A break entry, in 
effery purfornlng SYS 4. and the [RQ {a ehnaged, as the sereen wil show. 


M Gisplay memory contrats nna syntax UM fghj fgnf, where the two hex nud tesses Ape 
mandatory, opd the second mint be net less than the Firat. Sets af chet 
bytes ara eatput. precedil by 2: and their aturt address, like thts: 

“ek O07 8680 

.: GOTO Ke 77 DO O27 £5 TH AD AA 
1; OO7H% Ofte C4 3A 19 OA CH 20 TO 
1) 2040 BF 58 kU 3G 3A KX ON 60 


ce mne P mme  ta ttoe ee ee ap men na caters re wm ge MTNA om nme eT 


tt ee 





Programming the PET /C@M : -288- 10: Transition to mochine-code 


G Go w, Co run has two valld structures: G alone executes code from the 
current program counter, PC; G fghj executes code starting at the hex 
address here represented algebraically as fghj. The effect is similar to 4 
SYS call in BASIC, control being transferred to the new address. However 
.@ 027A differs from sys 634 in having the capacity to set values for the 
registers, stack pointer, and so on as a standard feature. 


X Exit to BASIC (no parameters) returns to BASIC in direct mode. This ta therefore 
the converse command to a SYS call into monitor. 


$ Save machine-code to tape or disk haa this syntax: 
.& "WAME (LENOTEC17)",01,0874,0304 — 
.@ "O: DISK NAVE", 06,0274, 0204 
for tape (cassette #) in the example; could alao be 02) and disk (drive 0 
in the example) respectively. The commas ore necessary, and help en- 
aure correct input. Note: SAVE finishes when the final address is reached; 
consequently, the ‘end address' must be at least one byte beyond the true 
@nud of the machine-code. 


L. Load machine-code from tape or disk hes this syntax: 

-L "WAME",O1 

-L "O: SAME" ,O8 

for cassette #l,and drive 0 of CBM disk with device #8, respectively. 
Adding commands to MLM. BASIC 4's monitor can be represented in a simplified form 
by « flowchart such as that on the following page, which shows the major features, but 
omits the details of line-input and so-on. If a command doesn't match any of those in 
the table, for example if .q was entered, # jump takes place with one level of in- 
direction, to the address stored in the-two bytes S03FA and $03FB. The default vatue 
in these bytes, put there when the machine is turned on, points to the subroutine in 
the monitor which prints .? and waits for another input. However, the pointer can be 
changed to a RAM routine which mimics the action of the monitor, enabling new comm- 
ands to be added. In this way, extended monitore of much greater versatility can be 
written for these machines, Note: TIM tacks this feature, and must be slightly mod- 
ified to include it. : 


10.3 Extended machine-code. monitors. 


Before we look at the extra commands offered by extensions to MLM, let's briefly 
survey some of the programs currently available. The first to become widely available 
was SUPERMON, which is available In. versions for BASICa 1,2, and 4. Several versions 
exist within each type. This program includes work by Bill Seiler, and Includes a dis- 
assembler based on Steve Wozniak and A Baum's Apple program, with a single-step 
utility written by J Russo. The whole thing was ‘combined, choreographed, and trim- 
med up’ by Jim Butterfield, and written In the form of a relocating loader, so that the 
code ja put into the top of RAM, wherever this may happen to be, and protected from 
overwriting by BASIC by lowering the top-of-memory pointera. The result is powerful 
and easy to use, Later versions have a machine-code routine to do the relocating; thie 
is much faster than the earlier BASIC: These are public domain programs; the append- 
leas Include Hetings of the BASIC 2 end BASIC4 versions, for readers who lack the 
programs, but not the patience ta key them in, 

Supermon haa itrelf been modified and extended by other users, The next major 
monlior was EXTRAMON, by Ril Sellor, which has more features than Supermon, and 
has been revised as MICROMON and also modified into other forms by non-Commodore 
software peoplo. The main differencos between thla program and Supermon are: 

(1) Machine-code ‘truce’ allows breakpointa, so program execution stopa when some 
address ie reached a pre-set number of times. Slnyle-step trace ls often too nlow to be 
practically useful. 

(ft) A relocater enablos code to be moved about In memory so thut It will run 
correctly. The command Js nol aa easy to use an thie bare description suggests. 

(ily An ASCH dump 1s provided, a0 tables and messages con bo identified and 
resd more eaally. | : 

(iv} Comparatively email, commatic, changes Include improved scrolling, ao that 
(for example) dinansombled cutput to printers In easier, and better acreen adlting. 

VIC has s monitor, avalleble an « plug-in module, which includes moat of these frat- 
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BREAK ENTRY 
(I.E, 'BRK' FOUND) 
Save A,X,¥, and SP 
gn_the stack. 
Store “b"; CLC/ 


CLD/ abort filuc/ 
pull SP,¥,X%, BA 



























(SYS cell,or EESET 
with diag. senso 
low), Store "C" 











Pull PCL, PCR 










PRINT C* or Be 


Load accumuiator 
with "BR" command 














Reset flags/print 
e,rtn. & '.*/input 
line {Accutulator 
bolds command} 


Compare commaods 
in table with 
accumulator 


Instruct ton 
found? 











JUMP TO Shaina sal 
Jump to address in 
($03FA). Default 
value prints 7 


: : R M G x L,S 


. ‘ 
ALT ALTA DSPLYR DSPLYM co EXIT LOAD 
& SAVE 


Jump to address 
in table + 1 















FLOWCHART OF BASIC 4 MACHINE-LANCUAGE MONITOR. 


nS I, 





uces, plus a dinassembler that works backwards. 

Among other monitors, BASMON is distributea by IPUG in the U.K., and ds 
essentially Supermon with additlons, notably to allow printout to o wide range of print- 
er types, and to aceept e Jarger range of Input formats. For example, a tibin of bytws 
van be entered directly Jato tha mint-agsembler. Like same other monitors the interrupt 
It vedirected to teat for the Step key, soa proyrrua in oan Infinite loop ean be nborted 
fusially) by ¢goftware, CSeetlan @,9 gives the methad). ELT RAMON is an cola rpect 
vernlon of Extramon; it is an American moniter, contelning: frecaralag: loa review by 
J Kiragan} asuerkled unacknowledged bits af cae frem diverse sources, deutiited age 
Compute! mayazine, Ocersionally one meets HUIMON in uaer-group eolicctions; this 1s 
ainply ene or other of the mola monitors ready celocatert inte the high end of RAM, 
and naturally thit will aperate successfully only if the recipient Cas has thy same RAM 
Morngo fitted, 


A Pe IT TA A RR NE A ORES SENTRA IT MR NL PRA AEE Rr SAE EET SR PT ee, opr ee or 
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tended monitor commands: (1) SUPERMON 


t sf 
st extended monitors ccnsist of machine-code followed by tables: in aueabiety pag 
se include assembler/ disassembler characters ($.#,X,¥ and so on), ope in ie 
ier data, followed by the commands (TFHDC, 4 and 1) and their rds ee 
dresses, which arc stored (for reasons connected with the emis is cae leer 
ion jue. Some versions have r 
itruction} one byte smaller than the true vai ; ae oeey 
i i > i fferent from those in MLM; this 1s Cy 
is not used. Nate that each letter is di ; ip cies 
leas iges otherwise they would never be executed, a eae iets Oe ea 
jons Hl . i lise some commands. i fs an 
‘cumlocutions have to be used to rational ar : 4 
single-step has te be something else - in fact, 1, perhaps implying ‘Ll step. 





Alter memory, then disassemble screenful of data a, F48C WD Ad 7A LOA $7848 


i 4 
The screen-dump (right) shows R tz qe 23 4 Pa A aon 
Supermon disassembly, consisting of 4 16 as 34 Cin 435 


screettful of disassembled data which was *F oohoK ad 42 TA LUA B44 
generated by .D 784C. In fact it is the 7499 6D FAQ} STA SY. 


: WA9D AD AS TA LDA ETAGS 
start of BASIC 2's Supermon. Up to three ee tae} STA SOIFB 






bytes on any line may be changed; when Janz GO ax ei 

Return is pressed, the new values are put Les ed “ et aac 

jnta RAM and the disassemble command rc Oe ayaa 

entered, with the same start point: #48 144A 86 84 srk $4 

in the example. The new serecn 1s there> ied “ je 

fore very similar to the previous one. Le he ee 

in i “On- JaaF HO 2F TA LOA STAZF, 

Assemble is a ‘ting! or ‘mini’ assembler, which con 152 a3 oa pet 

verts opcodes and addresses into the 74a} wy 2e 7A LD S7A2E, 

correct byte form (deducing the address- 7406 45 





7407 60 ATS 





ing mode from the input format), but not 
permitting labels or directives or any of 
the other features to be found on true 
assemblers. (See Chapter 14 on these}. 
The format is illustrated in the screen 
dump {right}. Pressing Return alone (or 
entering any erroneous datu) causes the 
error routine to be called, so a query is 
printed, foltowed by the monitor's ‘.! on 
the following line. While assembly contin- § Oe 
ues, new ',A‘s are printed at the start 2 SRIAcRTS 

of each new tine. [ta Caras 


0300 Lh #hOf 
oA 0302 10x FFF 

eA O304 STA §5O50,% 
oA G3O7 OFS 

SA 030A SPL $0364 
"A Q50A 1NC $0304 
yA O80 LUA $4508 
A Os1U CM #S4d 





” Calculate branch offset uses & format like this: 
(C aABCD ABFF . from which the positive or 
negative offset is caiculatcd, This is one 
byte only, and 1s counted as nogative if 
ity nigh bit is set. If the range ls too 
, the command reptics with a query, ; ; 
Tn van intcnaed to help with branches ina forward direction, but eae 
probably not widely used. Later Supermons (SGPERMON REL) droppe ; , 
D Disassemble is a standerd disassembler (with $ and # for hexadecimal and immediate 


mode, respectively), without labeis. See tha example above under ', 





F FI memory has three parameters, demonstrated 
by this example: 
F 3000 4000 AA ; 
hich hag the effect of filling RAM 
front 13000 to $4009 with $AA. This 1s : a “ s is Li “ 5 eh re 
useful In clearing an area of RAM. $00 go Mose GLA Tha 45 39 STA SD 
may Un used, SEA (NOP or ‘na operat- 70 74 4€ OF FN Ta, ALD AZ TA La TAA? | 


AO AS OW Fed (002 5 FA GT GTA OMA | 
ton') Is alvo popular, AO AS SE nu ua Mot, ws AS 8 Ue mex 
a 1 2 on 24 A th Pa Pah AO FO “TS 
fH Hunt memory (for bytes or ASCII] reports alt In leo 74 SF og Fy 244d G0 igen 


atupces of a byta combination ar a string jAt TP Fu oy FG tea aa Gt ROA AD 


op «TARE EGZE 52 64 3k 09 FA 
. 





PC IRQ bt AD XA HOSP | 
{ 
| 


of ASCEL characters, between two add- j2! wn Pn ue a nag be te pis < pe 
: se far if 21) #3 ON 46 EFL? © 2? 
renses. The two Cola are: a a se ate rai ts : mn es i 
JH ALICD CORY ARLCD)CEF] .. + PL On ED OD FS FESS AY F A 

i hace CUXF ‘HELLO PPOs FA OFFS FEST LG AS | CMP EOS 

. " ‘ 


: 7TS03 F800 FI Hae a4 At tem | 
I Single-step through program (see example, tlyht) 2 OF FE G79 68 LA 


A ST ail 


ee 
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performs GO to the focation indicated by the program counter, loading the 
values of the status reyvister, A,X, and Y, the stack pointer, and the int- 
errupt vector, From then on it displays the contents of the five registers, 
plus the location, disassembly ond corresponding byte(s), at each step in 
the program. The illustration shows the effect of running the program in 
memory from 748C; the program is Supermon itself, as listed in the first 
diagram of the three. Chupter 14 explains the working of this routine. In 
brief, each instruction is interrupted during its cxecution; this means that 
the interrupt is serviced when the instruction is finished. At this juncture 
the data displayed is collected together. This is the reason for the absence 
of the very first command. Note, for exuinple, how the Y-register remains 
unchanged; how BRK causcs a jump to a new part of the program; how 
the status register clinnyes as the contents of the accumulator change; and 
how a JMP retuins all the flags - the status register is unchanged - but 
alters the program counter. 

The speed at which single stepping takes place Is controllable from the 
keybosrd. < causes just one instruction to execute, RVS steps at a constant 
Blow pace; and the space-bar causes rapid stepping. Nothing hapya:ns if no 
key is pressed. Press the Stop key to return tu the monitor. 


P Printer disassembler as its name implies gives a continuous output to a printer; the 


syntax is .P 3000 3100 , or whatever other limiting addresses are to be 
disassembled between. This command is not available on all Supermons; 


early versions disassemble 22 lines only, as though the printer were the 
screen. 


T Transfer memory moves 2 block of memory. 


As the example (right) implies, only TRANSFER MEMORY 
three parameters are required, two 
to delimit the bleck of memory, and 
another ta indicate the strrting-point 
of the transferred bieck. The end- 
point cf the new block is implicit in 
these three values. 


»T t009 1t00 5000 


TRANSFER MEMORY IN THE PANGE 1000 
HEX TO 1100 HEX ANO START STORING IT AT 
ABORESS JOOO HEX. 


Extended monitor commands: (ii) EXTRAMON 


EXTRAMON's tabie of commands is ABDEFHINQTUW' and,. 


are closely 
emble, Fill 


Some of these 
similur to the corresponding Supermon commands, nanwely Assembie, Disass- 


memory. Hunt, and Transfer memory, Extremon's W Is Walk code, identical | 


to Supermon's single-step. The new commands ave as fnllows: 


B Breakpoint set & Q Quick trace let a program be aingle-stepped without any results 


E Exit 6 U 


appearing on thr screen, so that a graphics program can be watched as it 
develops at eny of the specds allowed by single-stepping. These are: 

« FOR SINGLE STEP; 

Rvs FOR SLOW STEP; 

SPACE FOR FAST STEPPING, 


The process aborts st a breakpoint, when a specified location is entered 
a pre-set number of times, Each command has alternative ayntaxcs: 

.B 2245 breaks when location $2345 is entercd for the first time; and 
.B 2345 AO breaks only when it is entered the 160th time. 

.Q traves with the duta currently displayable by .R, whereas 

.@ 2000 alters the progrom counter to £2000 (so .& isn’t necessary). 


Undo are complementary routines which respectively set up and undo an 
emergency exit routine From an infinlte loop. This is valuable when & pro- 
fram appears to be loxt in an infinite loop. (The rationale ia explained bry 
seetion 4.9. Tt inveives redirection of the interrupt vector through a tent 
roulins, with # fump to the start of the monitor If the teat succecda, This 
methed fails if the interrupt is reset - for example by cuasette tape activ- 
Ity > or whth 'X2' typo crashen, which are not suaceptl>le to thia cure). 
In ordur to permit normal une of the Stop key, a combined keypress ty 
needed to trigger the return to monftor, 40-calumn machines rely on both 
zs und Stop, which are chevked by exaairation of SEH12, Two kaya pressed 
at once register the logicnl AND of ench separate hoy: $6F In Hils case, 
The syntax la simply ,£& and .¥ in each case. 


* METI neta: ENT A SENN Farrage rt AR, RNA CURRED XR NON GST NRA oS on TY AU 
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‘Integrate memory’ (not to be confused with Supernoa's single-step) provides a hex 

dump of 8 bytes, plus the equivalent in ASCII, so that tables, messages, 
and so forth are readable, It is analogous to the .M command, except that 
(i) ASCH is present after the hex, (ii) the coloa of .M is replaced by @ 
new symbol, ', Thus I and ' between them perform a similar function to, 
and may be used in place of, M and :. There ig however a slight syntax 
difference: 
TE ABCD continues to the end of memory (FFFF) untess stopped, whereas 
,R ABCD elicits the ? error indication. 
“L ABCD BCDE behaves like .# ABCD BCDE and ceases at the second address. 


el FoOO 


1 FOUO 54 4F 4F 20 4D 41 4E 39T00 MANY 
at FOOS 20 46 49 AC 45 GS 45 49 FILESFI 


'New locater' is a true relocater, not just a memory-move routine bke .T . It has 
six parameters, three of which are identical to these of .T, and which 
specify the start and end addresses of the chunk of code to be moved and 
the new starting-point. The end-point is of course implicit in these. Two 
types of code may be moved: continuous machine-code, or ‘word tnbles', 
ile. individual bytes of datu not intended to be 'run' as a program. If we 
consider machine-code first, our chunk of code may net be an entire pro- 
gram; and if it is a subroutine or subprogroam, it may be called by code 
outside itself. So, in addition to an indication that the code is of program 
type, the remaining parameters define the range to be examined for calls 
to the releested code. "Word tables’ can also be referred te externally, but 
do not themselves require any internal chanpes of the sort required by 
absolute addressing. (See Chapter 13 on relocetion, for further details). 
The way to use this command is (i} Put zeru bytes into the receiving area 
of RAM (.N will not move BRK instructions), tii) Move the tables next, 
end Ciii) Move the code, The examples given in the instruction program 
ere 


N 


oH 7930 TIFF $9GO 0400 8000 


aM 7000 77FF 1000 9400 S006 W 


in which the whole of norssl RAM from $0400 to $8000 is examined for 
references to $7000- S7FFF, and, if any are found, are converted into 
the range $1000 - SIPFF. Even if many entirely disparate machine-code 
routines coexist in RAM, this will probably be successful, since it is not 
likely that any of them will reference exch athers’ tebles or subroutines. 
This routine will net relocate zero-page programs, it will relocate KOM 
routines, which can be uscful, as they are modifiable in RAM, but tables 
may their references rewritten manually, to make the resulting relacated 
eode compact. 


Modifying monitors. An advantage of programs stored in RAM ts their accessibility to 
the programmer. Given some exparience in machine-code, it is possible to intreuduce 
modifieationa to carry out functiona otherwise unatteinadic, but at the same time to 
preserve the Input and fornatting features which make monitors easier to use than ad 
hoc picces of coding. On the other hand, this procesa ls tricky If a source listing of 
the routine doesn't exist, becuse machine-cade Is typleally weitten In & compact form, 
fitting together like poli:-hed mahogany’ as Churchill weate. (Of Latin sentences! ), 
Let's consider a concrete exemple; the Yunt' function mnuablesy us to search any part 
of RAM for any sequence of bytes which will fit inte a single Hine; 
.H BOOO FHF? AD 44 £5 
searches BASIC 4 ROM for threa bytes which dissamble as LDA ads. 
to allow the use of a ‘wild card’, e.g. 00 in this example: 
.H BOGO FFFF 85 FA 06 O) BS FC 
aasuming our only aeftwore toot is an extended monitor, and not, say, an sasembler 
with a lnbel-generating dloasaembler? The object is te peonmit Flunt in whieh the bytes 
fn the positions correspunding fo 06 mny luke any valne, so STA FA any 2 bytan 
BTA FC will be acught Wy the perticular Input line Just quoted, As le happens, this is 
an easy modification ta make, To iiustrate the method, J use HASIC 2 Supermon in 


What munt we do 


TTR PRET NERA TE Ae rte Lg MN PE TNE SRT LNT | SIENA RPT RR AE TE TN, pee re 


- 
aw 
Pits 
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. ea 32K machine. Other monitors ané memory-sizes wil therefore not give identical dis- 
assemblies, but the methed should be clear enough. 

First we have to find the routines which process H. By examining the tables (ot 
the end of thé program) we can find $43 (ASCH for H) within the table of other ASCIL 
characters which mske up the edditiona! cummands, We then use the relative position of 
H in ita table to deduce the entry address of H, oy looking through the programs for 
a tuble of addresses whicn seem to correspond to entry-points in the monitor. ff. as is 
usual, the address is entered dy two PHA coaimands followed by RTS, we must add ! 
to this address. The resulting possible entry-point 
can be checked by inspecting the code for CMP #$27 Section of unmodified code; 
(checking for ', as in .H ABCD BCDE "HELLO ). At +, 7H2} a0 Ba 5TX Sad 
this point the code separntes; if we follow the branch ., 7885 29 D0 FD JSR $eEDO 
~ since we are not concerned with the ASCII string ., 7BBe A2 06 Lbx #$00 
test ~ we find a block of code from which exit oecurs + ae oy tars) 

i : ; 7" “- % {£FB),¥ 
Fee cteaa he © ee De ere nent a vuln cee mee Re: Se 
ry i +, 731 DO OC SNE $7BCF 
er. Finally, we reach the code where comparisons hs Toa ck iNnY 
are made. (See the disassembly, right). Location Bd ., 7Bc4 Fe INX 
: holds the number of bytes being matched; 7BBC and ., 7sC5 £4 B4 CPM $e4 
; IBBE compare the contents of memory with the con- +s 7BC? DO FR BNE $7a5c 
tents of the buffer, and, if these are equal for all ++ 7BC9 20 GA E? JSk SE76A 
X values, the address is printed, to show that a se 7ecc 20 CD FD JSR SPOCD 
match has been found. +. 7BCF 20 DS FD JSR $FOO5 
, et bt +, 7BO2 AG OE LDX SOE 
ok To introduce our modification, all we need do «, 7BD4d DO a2 BNE §7B68 
is insert a test for the presence of our ‘wild card’ +, 78BG 20 D9 7A JSR $?AD9 
byte, and, if one is found. treat it as a genuine «+, 78099 80 DD BCS $7BAS 
match. The second batch of code (see right) is one ; . 
vergion of this, Line 7BKB and THBD bytes in alt) Gade atten: medi flea ion: 
, compare the buffer contents with #00 and branch past ++ 797K C9 27 CME #827 
the memory comparison if #00 nas been found. (7BBC *: 7481 DO (15) BNE $7833 
way be altered to any other value, should a #00 wild "¢ ae i va Hi 3k pan * 
card be unsuitable; namely when #00 bytes are them- 7’ sates kes pice Bona 
selves sought}. Because of the four-byte patch, some ie 7B9A 20 CP FF JSR $FFCF 
branches have to be slightly changed; moreover, the ., 7asp ¢9 Ob CMP #S$0n 
hunt function for ASCII strings cannot be made to «, 7BAF FO 22 3EQ $7583 
coexist with our new function, without a great deal ++ 789) £0 20 CPX #S20 
of rewriting. In practice, the new version would be = ** [tse . 2 . aga Pea 
i f ae EB? c 
aa under a different name fran the 13899 90 GA) BCC $7B65 
} spcaat «, | 78958 9D 10 02 STA $0210,X 

All the modifications are marked on the second ,, | 7p9E £8 INX 
pleee of code, including the chunk of code which was ., | 749F 20 CF FF JSR $FFCF 
relocated 4 bytes bock in RAM. Apart from rewriting ++ | 7BA2 cy Ou CMP #SU0 
the comparisons, the remaining changes only dealt “F ache pi a a ee hana 
. . eer . SR $E 

j with recalculating branch destinations, ; . Fuad 90 é) Epis rele 

Rather obviously, this type of adjustment cun't ,, | 7ua8 £0 23 CRX #$29 
be made withovt a fair amount of machine-code exper- ., | 7HAD DO EC BNE $7835 
fence. In the swne way, comparative beginners will ., | THAF 86 BA STX $B4 
not find it a simple mutter to decipher the workings +. | 7881 20 Dd FD JSR SrDLI 

{ of these monitors. Supermon, for example, starts +4 | 7BBd Az 0 Lox #$00 

with a series of ten subroutines, which have the ++ L7BB6 ad 00 Upy #$00 
following function: fa 7ane 70 10_02\ aarp as 
i e +, 7BaN co OO CMP #500 
() Reset top-of -BASIC and USRCMD, ypnol Fo 04 REO $7HC2 
(li) Search for extra Supermon instruction; * oaue\pt Fa CMP ($EB),¥ 
{iil} Decrement contents of (ED) or (FB): +, 7H DO OC BNE $7BCF 
(iv) Get next character from Input, ignoring spaces; ., 7003 Ce INY 

i {¥} Input hex address Inte (FB), ignorlng spaces; oe «TRCA BB INX 
{vl} Skip a character. Get hex addresa Into (FB). vs 7BCS E4 Ha crx Spd 
{vil} Print X spaces, +, Fac? OO BNE $7858 

(vUli) Increment address in (FH): ie Ye ea eee. sae epee 

: ic} Exehanjre conlenty of FL and PC with contents 7! See 20 - FD geR-SFODD 

4 of O20 and 0250 respoctively; 3032 AG UF : Lik $b 

H Ux) Test for equality of (0204) and (FB). Wequat, «, 7d vO 92 ANE $ /PhH 

5 Z fing In wat; af fous, carry Gag is clearod, ce Tepe 20 DY TA Ju $7A" 

; ee TuHbO Bnew) bes $784 
v. PROB ac be en JME SFOG 
ae TIME 20 94 7K Je §7AI 

a, TORT Ob UL 02 STA $U20b 

4 

’ 


egies 
SORTER MRR AT rut tee mR IR HST AP Tm NGL PAP PEN TOT AAT SH RRS SENET: ATA ENTE IF ar 
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0.4 Monizors In BASIC. 
though good machine-code routines are unquestionably superinr to their BASIC 
sunterparts, there are often advantages in BASIC monitors to offset their slow speed 
n@ relatively large memory requirements. (i) They con be transferred between PETs 
ithout compatibility problems, execpt possibly with regard to ioz -of-memory pointers 
r printer formatting. This may not be true of machine-code programs, leaving the 
could-be user with the options of modifying a present program, or gving back to 
LASIC, probably temporarily. (ii) The coutrot of BASIC is familiar: the ability to stop 
he program and LIST it can be velunble. Uli) BASIC is easily changed to allow for 
matiish variations and differences. Por example, a new printer, with different comtret 
haracters, can easily be accommodated in ABASIC. Decimal numbers can be used in 
lace of hexadecimal, or alongside hexadecial, if required. Different opcode conven- 
ions cum easily be implemented. Changes of this sort are far more cifficuit in mach- 
ne-code. 

Beside these reasons, writing & disassembler is a useful exercise in undersiand- 
ng a chip. The next page has PET /CBM 6502 version which cuns on all madels. 
\ simplified Mowehart of ity logic (see telow) shows that it operstes by wiiting for 
nput ef a sterting address, then disussembling fiom that pint by peeking the ac- 
tress and converting it into the eyuivalert opcode form, and looping back to repeat 
he process with sulsequent aduresses. As an example, suppose 0274 holds this: 

,1027A 20 F4 SF FO FA 60 00 00 
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dn entry of starting uddress = 027A, the program pecks O27A, finding 32 {in decimal). 


his figure corresponds to "JSR" with address mode IG. This is processed by the 
wibroutine at line 100, which prints the following two bytes, in hex, in the reverse 
order, Meanwhile, this instruction has 3 bytes (NH=3). So JSR FFEd is printed, and 
‘he addcess to be peeked is updaicd, now being 0Z7D, and the process continues. 

if bine @ includes @ poke to lower the top of momory, (see HIMEM in Chapter 5), RAM 
seiow $8000 cen part!y be used ior machine-cade. Line 10 provides a ‘warin start’, re- 
antering the program without clenting the variables. The data storage method used 
jere causes no garbage collection delays with any version of BASIC. 


( START 
TNEITIALISE 
Set up tables of 


opcodes & their 
addressing sodes 


INPUT STARTING AD- 
ORESS FOR DISASSEMBLY, 









TABLE OF VARIABLES. 


=cucrent address (usu. of opcode) 
& L$=decimal end hexadecimal nust- 
ere for interconversion 
addressing mode, coded 0-12 
)ropcodes' addrese modes 
inumber of bytey in current 
inetructlon (always 1-3) 
‘sdecimal value of opcode 
'S¢jetable of opcodes by decimal 
value (#.g. OF$(O}="BRK") 
:peck value of current addresa 
(usually corresponds to opcode) 


TABLE OF BUBROUTINES - 
















0 Print @-dyts hex number givea L 

10 Print 2-byte bex number given L 

10 Cunvert 4-byte hex number iuto L 

50 Convert 2-tyte hex number into L 

10 Frint hex number from next two 


“> N 
— 
PRINT ONE LINE OF | {| NUT AN OPCODE 


ee 


DISASSERHLY aera eee 
Bees rg saa tint 29 
Bytes. 19 fevorsh Sraee ; Locat ton, opende ,& | i 


90 Print next oyte to hox pone date /addrens 


yO - TI Print atidress or data after 
the opcodn, punctuated in tad 
standacd way. Seo Che AEM: for 
detailu of mudes M, 0-12 

HOG Fnitialises... 

60 {0 warm wturt... 

NOO Dinaseenpied until spacebar aa 
prozeed (seo Line 3070) 


bare 





UPDATE ADDERS! 


AdQregn = 
Addr,#i, 4, 07 ; 


rem tn ye me 


= 


PEGE ASI LT I ne veer Rae ETI aR TERE EOT eee tioees, ett em ET” ee 





| 
: 
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O CLa: GOTO 2000: Rim FITS 7K WITH SOME REMS REMOVED 
10 GOTO 2550 


100 
200 
300 
350 
405 
S0u 
660 
610 
620 
610 
640 
642 
650 
660 
676 
630 
69) 
790 
719 
2000 
2010 
20206 
2030 


2500. 


2510 
3900 
3005 
3008 
4003 
3010 
3615 
3920 


3922 


3425 
3030 
3035 
3040 
3645 
3950 
3055 
3366 
3065 
3066 
3070 
3075 
$990 
5016 


5320° 


5230 
5140 
345u 
5960 
$070 
5090 
5990 
5100 
4119 
Si2a 
5430 
$140 
4150 
5169 
“avn 
“urd 
VG 
Saty 
elty 
Vaan 
Sf3y 
SPAD 
vr an 


L=L/4 
L*L/1 


096: PORT]1TO4: Lash: SH INTCHRS( QA+L&- (L499) #7): L616 * (LLG): NEXT: RETURN 
G6: FORT* 1TO2: LAHKL: PR LTCRRG( 48 HL N—{LO>9) *F 177 La16* (LL) NEXT: RETURN 


La0;TORI#tTO4; LA*ASC( MIDE (L$,J) ):L=1 E*L+La-44+(L0264) “7 :NEXT: RETURN 


L=0;£ 
FORK= 
L=Pre 
PRINT 
Quscs 
FRINT 
PRINT 
LePSeé 
Loca 
GOSUR 
PRINT 





GOSUB 
PRENT 


ORIZITO2:LAMASCCMTLS (LS, 0) )fLeTG*L+ Lh -aG+ (L39G64) *7 NEXT: RETURN 
PTOISTEP -1; LEPSEK (CA+K ) ; GOSUB 200 :NEATERETURS 

K{CA+1):;GOSUB 200: KETURN 

"(";; Gosum 400: PRINT ")"- PETURN: REM UNTTRECT JUMP 

500: PRINT “,¥"; KETUKN: FEM ZERO FAGE, INDEXED SY Y REGISTER 
'oms; COUUB 520; PYINT ",x)%: REPURN: REM INDEXED INDiRECT (ZERO PAGE, X) 
*("5: GOSUB 500; PAINT "),4%: KETURN: REM INDIAECY INDEXED (ZkRO PAGF?,Y 
K(CAtI): IEE 0912? TdEN L=b-256 

245: GOSUB TOU: PRINT: RETUBN: REM RELATIVE ARANCH 

400; PRINT ",Y7: RETURN: REM ABSOLUTE, TNDEXUO BY ¥ REGISTER 

Pe":: GUSUB 500: PRINT: KETURN: REM iMMEDIATES 

400: PRINT ",X"; BOTURN: REM ABSOLUTE, INDEXED BY X% REGISTER 

500: PRINT ",X": R2PURN: KEM ZERO PAGE, INOEXRO BY X REGISTER 

500: PRINT: RETURN: Ria ZERO PAGE 

400: PRINT: RETURN; HEM AsSOLUTE 

+ RETURN: REM IM@.LCEO AND ACCUMULATOR 


DIM DPEL?755), MR(255): SPs=* ‘ 
Foe J = 0 TO 150; REM TOTAL OF 1591 DIFFERENT OPCONE/MODE COMB [NATIONS 


READ 
NEAT 


GP, OP$(OP), M&(OP) 
a 


INPUT *ASSEMSLE OR DISASSEMBLE"; L$ 


Ir ¢.& 
INPUT 
Gosua 


<"AN GOTA 4090 
*DISASSEMLLE FROM"; LS 
399; CARL 


INFBUD "DEVICE#™7N 


OPEN 
L=Ca: 
B=PEE 
IF OF 


LaP:FRInT “ 


NBT2: 
If he 


R,W: CHO N,? 

PRINT L LEPTS(SPS, 7-LEN(STRS(L))}.2 Gost 100 

K(CA): M=MECP) 

S(P) <> "" THEN 3025 

7; :GO5UB200: PRINT® 777": HBal: GOTOI065 
IF M20 OR M=o OR M=7 OR M710 THEN NE3 

11 THEN NB=1 


PRINT " "3 
FUR K=0 TO NG-1 


wernt, 


K(CAtK): GOSUB 209; PRINT “ Ne 


NEXT & 

FoR J = NB TO 3: PRINT " “3: NEXT: PRINT OPS(P) * "Fr 

OM Mt? GOSUB 600,610,620,630,640,650, 660,470 ,440,690, 700,710 

CA+CA RNA 

CLOSEN 

GET L$; IP L& = " “ THEN 2500 

Goto 3909 

DATA 0, BRK, 11, 1,024, 2,5, 0R8,3,6,A5,9,8, PAP, tt,9, OPK, 6%, IC, ASL, 11 

DATA 13,O0PA, 10,174,A5L, 19,16, BPL,4, 17,ORA,3,21,OHA,&, 22,ASL,6,24,CK0, 11 


DATA 
DATA 
DATA 
DATA 
DATA 
DATA 
DATA 
DATA 
DATA 
DATA 
bat 

DAT, 

DATA 
DATA 
OATA 
DATA 
ONT 
VATA 
DATA 
hata 
DATA 
LATA 
DATE 
OTA 


COON mame cee ee 


25,00, 5,29, 9PR, 7, 30, ASL, 7, 32,0SK, 10, 33,AN0, 2, 36, BIS, 9, 37 AND,D 
38, POL, 9, 49,PLP, 11,41, AND, 6,42, ROL, 11,44, HIT, 10,45, 00, 10 

46, POL. 19,40, BML, 4,49, AND, 2, 53,AND, 4, £4, ROL, 8, 56, SEC, 11,57, RNIY, S 
61 ANG 7, 62 .ROTe, 7,64, RTL, 11,65, FOR, 2, 64, FOR, 9,70, 05R,9, 72, PHA, I 
73, f0R, 6, 74, L7K, 11, 76,0MP, 10, 77, FUR, 10, 78, CSR, 10,80, BV, 4 

81, BOR, 3. Hy, EVE, 8,25, LER, &, BA, CLE, 14,49, 80%, 9, 93, ENR, 7 

94. LSR, 7,94 -PTS, 11,97, ADC, 2, 104 ,Ale7, 9, 102, ROR, 9, 104, PLA, V1 

107, Ab, 6, 196,80, 1h, 108,JMP,0,109,ALC, 19, 110, ROR, 19 

142,845,4, DID, APC, 3,117, ane, B, PIB, Re ,9,120,SET, 11, #21, ADC,5 
125. ANC - 7,12), BUH, 7, 129,STA, 2, 132,56%,9, 173, 5TA, 4, 134, STH, 
436,DEY, 14,134, THA, 11, 140,STY, 10, 141, 57A, 10, 142, STK, 10, 144, BCC, a 
145,8TA, 3, 144, CTY, 8, 143,578, 8, 150, 50%, 1,192, TIA, 14, 153,80A, 5 
154,9%3, 11,157, STA, 7, 140,L04,6, 161,008, 2 

162, 00%, 5, 14, L0%, 4, 109, EN, 5, 166, LOK, %, 16H, TAY, 14 

169, LA, 6, 170, TAA, 11, 1PZ LY, HD, 172, LOA, 49, 174, LOX, 10 

F7ALB7G, 4, 177, EEA, 3, 1BO, LAY, B, TAT, LOA, A, WZ,LOX, 3, ING, CLY, V1 
1H5, LOA, 2, BIE, T5*, 11, THA, LE, 2, TD 7, 190,108, 5, 142 Cre, 6 
TD,OMP, 2, td, OF, CRP 8, VIR GES, 9, 290, THY, TT, 204 ON he 
INTO, VI, 268,10, WD, 205,0MP, 10, 286, DET, Ma, AGH, BAB Ay AY OME 
213, 0MP NM, Roa irs! Bei, Cl, 14, 204 OME, S221, CME, 7, 222, 0k, 7 


’ 


224, CPE, PPS 














' 
7,2, 220, CPR, 229 ,UNC, 4, 230, INC, 4, DIA, ENK VI 

244, Sheet, 2h, OP, TT, 2TH CHK, WD, AP, Mey 2M, Te, 1, 249, BRD A 
DAL, CHE, 1, 24 Ee 2Ae TN, I, OA, END, 1% 











D4 MIL, ny 2th, 2 204, Int), ? 


ee A mR IN RZ RT NIM RTE So Lem cee FL errr nts tm 
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Tiny assemblers in BASIC are a little harder to write; each line aust be validated, 


and the addressing-mode deduced from the input. The additional batches of cade (see 
below) may be added to the disassembler, and called from line 2503. They do not pro- 


vide full validation, but are designed for ease of programming. Lhe rationele of sttb- 


poutine 600, which determines the mode, is illustrated in 
this table of addressing modes, Numbered as in the pro- 





gtom, arranged es examples in culumpar form, so that ABS, Tkb. 
the leagths of each complete instruction and the pas- 0-P,Y¥ 
itions of the punctuation symbols cun be seen at a glance. | (IND, X} 








Lines 30935 ~ 4045 check for the existence of the {1ND),¥ 
encode and for the correctness of Its addressing mode, BRANCH 
relecting “FQR" and "PHA 1234", for example. The sub- | ARS,Y 
routines starting at $00 extract the address from the IMMEDIATE 
string which was input: and lines 406) ff, poke the AHS ,X 
tassembled’ values into KAM. Note that line 4915 puts O-P,X 
a * before the input; this enaules commas to be accepted | 0-PAGE 


without extra ignored, The pokes apply to BASIC>1. 
This version docs not include '5' syinbals before 


THPLEED/A 


hexadecimal numbers; there is littte proviem in introducing them, however. In some 
(e.g, line 3010} the TAB function has been replaced by 4 longer expression, as 
not all printers process TAB. Line 30U6 may need to open a file number > 127. 


cases 


600 L-LEN{ASS) 
605 IF £23 THEN M+t1; RETURN: REM IMP ED 
St0 IF i=e THON Me 9: KETURN: Eq GERG PAGE 
615 LF L=? THEN B= 6; RETURN: REM [AMZDCATE 
A20 LS-MIUS(ASS,5,1) 

B25 IF LS2°%X" THEN M~4; RETURN 
B30 SF pe-y THEN M=1: RETURN 


REM ZERO PASE,X 
RIM 2FRO PAGE, Y 





B35 if L$e"," THEN M22: RETURN : RIM inSIREC’, xX 
P40 IF LS") * THEN M53: RETUR: REM INDIRECT, ¥ 


845 LSEsRIGHTSOASS, 1) 

O50 Tr Lee"K” AND L#16 THEN M=?: RETURN : 
B55 [bP LS-"y" AND L*10 THEN M=S: RETURN : 
$60 IF Ta¢*)" AND L210 THEN M=0: RETURN : 


REM ABSOLUTE, X 
REM ARSOLUTE, Y 
REM ARSOLUTS TNUIRECT 





B65 IF LEFTES(ASS, })="S" AND MiTS{ASS,2,1)¢>"0" THEN M=4: RETUKN: REM BRANCH 


870 Ie Le8 THEN M210; RETURN: RIM ARSOLULE 


B75 PRINT "MONE 7":4412; RETUPN: REM CALCH ALL OTHER INCORRECT ENTRIES 


900 PrG:L=-4:GOSLR S65: RETURN 
905 PeGsL:2:GOTo 960 

910 PsG:L=2:G071O Ye 

915 Pr6:L32:G0TO 960 

920 p=5:062¢:GOSUB 960: GosUB 309 

O21 Lst-CA-2: UP £9127 Of L<e-128 THEN PRINT "BRANCH? “1Me 12 :RETVRN 
93? TF Lif THEN LeL+256 

92) RETURN 

925 Bs5-L*g;C0TO 960 

9430 £=6:L92:GOTO 9460 

45 Pah L=4:501O 960 

940 PH5:be2; 407 969 

945 Pals Le2:GOTO 960 

959 Pw5: Lad :SOTO GAD 

560 LSsMIU$S(A5S,P,L): RETUR?I 

4000 INPUT “ASSEMELE FROM"; LS 

4005 GOSUB 300: CAL 

4010 LeCA: @HKOIT & TAB(T)212 GOsuR 100 
400% poem 527,34: Pike $25,413; Tuer * 
4020 Lr aS$e"EtiV"™ COTO 2509 

4025 COS + LEFTSIASE, 3) 

S030 GosLUB ANN: TR M12 THEN 4016 
40395 FUR HO TO 255 

4040 LF COSCOPELS) THEN NEXT: PAINT "OPCGDE?": COTO 4010 
4945 If MerMa(S} YUEN JeJets GoTosnad , 

4060 Med: TR MS? Oe M=5 OR Me? Ge Mel THEN Nitvd 

4055 Te Meld THEN hee? 

4UL0 Putk CA,G1 EM PORK OPRGnE DCT MEMORY 

4065 TF Seed THEA 4909 

4070 CR Med PME GOnlis D201 GF Mal2 Tur ani 

4975 GF Med THEN Fork CAt1, fi Get? ane 

4000 ON MHD GOS GN, V5, 91S, 15 920, 925, 999, 299,949, 445, 95d 
4005 ER ONS? THEM TUB AND 





” ;ASSEMBLZRS 





Baer CArt, Gt KAA OHE ADDREGS ETE CONOY) THot— 


4990 LR SAAD THEN CUS) 200, POR CARP LAIN UL/Z 50) 82552 Pore CANT L/L 56 


AION CAMCA NIE TOSI 


PY ga ORE en A re I to TE Rd It SL WET AGT ee Pe 






eee 


, 


Z : oad fe si ‘e) same . ‘nisi ah 3 nei 


eat? 
et pare ten 
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10.5 


{ shall assume in this section and subsequent chapters that the reader has a rersoneble 
grasp of hex arithmetic, and has eithor a BASIC or machine-code monitor available. 
Equipped in this way, s/he can experiment wilh the 6592 and become confident in its 
use, This chip is not particularly easy to program, One of the designers of Commod- 
ore's ‘Micru-mainframe' has said, among other things. ‘lf you can program the 6502 
you're a geniust and ‘After the 6502, everything from then on is easy’. Without going 
es far as this, it remains the casc that machine-language cannot be mastered overnight. 

We'll look at some of the simplest instructions and addressing-modes in this sec- 
tion, since progression from these to the more subtle instructions is a natura) route 
which most cr all programmers (I suppose) take, Each exemple can be entered either 
from the machine-language ainitor in the CBA (SYS 4 is usually the easiest method of 
access), or via a monitor; { have used the convention of prefixing hex numbers with 
‘'§', which however should be omitted if the BASIC rautine is the previous section ts 
used. There are, of course, many other examples throughout the book: SYS and lSR 
in Chapter 5, and some graphics routines in Chapter 9, ought to be fairly accessible 
even to quite inexperienced programmers, 





Example 1: poking a single character to the screen, 


Starting at 027A, enter the following 6 bytes, either with .M, or with a monitor's 
assembler. The two forms are exactly equivalent to each other, and are simply differ- 
ent ways of writing the same information. The opcodes are more readable ~ with exper- 
jencc ~ than the individual bytes, but either farm can be deduced from the otver, Thus 
disyssembly of the bytes entered by .M will yield the result shown; and inspection of 
memory efter entering the instmictions from an assembler will show the same pattern of 
six bytes as though entered using MLM. 


-M 0274 AS 00 BD OO &O 60 xx xx $U27A LDA #$00 
$027C STA $8000 
$O27F RTS 
What dues this shori routine do? $027A = 634, co SYS €34 causes the code to execute. 
RTS, ‘'ReTurn from Subroutine’. has tie effect of returning to BASIC, so we may 
execute SYS 826 as often as wo like frum direct- or program-mode BASIC. [ts effect is 
to print an ‘'@ symbol in the extveme top-left corner of the screen, unless the sereen 
serolls and the charseter is lost. This tap-left screen location, as we alreacy know, is 
location $8000 in RAM. This shauld give a clue to the meaning of ' STA $2060 '. In fact, 
we can read the eode like this: Loud the accumulator with #0 (i.e. value zeyo), store 
the secunulater in $8900, and return to BASIC. The xccumutator, abbreviated to A, 
and shown by MLM as 'AC' when the registers are displayed, is an B bit locetion within 
the ehip itself, which can therefore be loaded with any value from 9- FF. Our example 
has the same effret as poking $8080 with zero. 

Con we do more with this? If we POKE 635,1 then SYS 634, the letter ‘a’ or ‘A’, 
depending on the upper- or lower-case mode, appears on thu screen; and disassembly 
shows that our short routine now rends: $027A LDA #$01 


027C STA $4000 
$027F HTS 
because 027K was changed (from BASIC) into 1. This direct-mode atatement: 


FOR J=Q TO 255: PORE 635,3: SYS 634: NEXT 


runs through the entire gamut of characters: very rapidly changing, they are all dia- 
played one efter the other in the top-left corner of the CBM screen. The machine-code 
hag deen execttted 256 times, each time in e stightly different form, being: Lett with 
its first Instruction changed to $027A LDA @$FF, because SFF, 255 in decimal, waa 
the Inst value put Into $uc7R. 

When thl¢ is fatety clear to you, louk at the .M form of the six bytes again, 
Note that the addres3 $4000 ty held in reverse order, with $90 preceding $80. This Is 
a feature of all J-byte commands in the 6602 aud many other chips. (ut not the 6809). 
If wa modify O27D's contents SYS 634 will load the accumulator, then store it, not In 
$8900, but In a tocution from s4udt - $80FF, die. within the flrat few Unes of the 
ketcean, Try thla: 


FOR dQ TO 255: PORE 635.0; POKY 637,J: £45 €34; NEXT 


{xx may be any valuc)- 


which calls the routine 256 times again, but thin tine prints each chafncter separately 
OG tha ecreen, ja ancending order. Tia flaal form of the routine, after 255 hag been 


a 


een enn On One Lo ST ee Oe a tee 


emandlaeeat mta yaad stir A mS a Ht So AA IE 
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$0274 LDA #$FF 

| $027C STA $80FF 

° $u27F RTS 
You should now be able to print any character into any locatinn om the serecn, after 
a certain amount of calculation. Section 9.1's table of PET/CBM acreen memory cnar- 
acters lists the values corresponding to each poked character; and section 9.1 hes a 
table of the hex values of the atart of each screen-line. 


Exampte 2: indexed addressing. 


Enter the T-byte routine $027A LDA #$00 
$O27C TAK 

-M 027A AG OO AA SD 0D BO 60 xx $027 sta $A0C0,% 

(xx may be koy Yoluc). $0280 RTS 


This intruduces two ideas: the idea of the X-register, und its use as an index. TAX 
stands for "Transfer Accumulator to X-register’; X is an 8-bit register. similar to the 
accumulator, into which the contents of A are louded when TAX is executed. $8000,X 
{a a special notation, meaning the address $9000+X’s current contents. That is, what- 
ever value is in X is added te $8000, and tne resulting address used in the command. 
Since X is 8 bits long, the range of addresses spanned is $800G- S80FF in our example. 
What heppens when SYS 634 runs this code? We can read it like this: Load A with the 
value zero; transier A to X, so that X now wlan holds the value zero; store A in the 
address $3000 indexed by X, which Is therefore $9090; snd return to BASIC, The 
effect ig to put '@ in the top-left of the screen ayein. 

POKE 645,14: 57S 634 runs 
thia modified version: Sanne a #501 


$027D STA $8000,X 
$0286 RTS 
which puts 'a' or 'A'’ In the top~teft-but-one location on the screen. This happens be- 
cause STA $8000,x when X holds #1 is understood by the 6502 to refer to $8001. 


Example 3: incrementing and branching te generate foops. 


Type in the next routine, which introduces a few more introductions. Once again, the 
PET's moniter and the ‘assembler’ and Gisussombler are dealing with identical data; the 
appearance may be different, but the essence is the same: 


.K 027A A2 90 8A SD OO 81 £8 DO $O27A LDX #300 ;LOAD REGISTER X WITR #00 
M0 «0282 FG GO xx XX KA KX XX XH $O27C TRA SYRANSFER X TO ACCUMULATOR 
(xx may be any value) $027D STA SKOAO,X;STORE ACC'R IN $80A0,% 
. $0260 INK p INCREMENT X-REGTSTER BY 1 
$0281 BNE $027C ; BRANCH IF RESULT IS NOT O 
$0283 RTS TASTUAN (TO BASIC) 


Kow enter SYS 634 from BASIC. The effect is to print all 256 sercen values in 256 
adjacent locations (i.e. reading across, then down), starting at the fourth line of the 
screen, or the sccond with an 60-calumn screen. How docs this work? The instruct- 
ions have been unnuteted to help make the process clear, (These comments won't be 
accepted by many tiny assemblers, so don't try to enter them with the program). 
First, X, like A, can be loaded with any 8-bit value; #0 tn our example, TXA 
transfers X to A. At this stage, therefore, both hoid #0, of, in terms of bits, 
C00 ufud, $80A0 is the start of a line on the sercen; when X holds #0, the indexed 
address 80A0,% is therefore calculated to be $00A0. So #0 in poked inte $8040. The 
next instruction, [NX, adds | to the contents of the X-register. If the value {fs #FF, 
it ts incremented to #0. So long as it is not zero, BNE (Branch if Not Equai to zere} 
will cause the program to jump to the addrezs specified; in the exemple, therefore, the 
code frun O27C to 0281 Is executed 256 times, the vatuo of X at the start of the loop 
belng tnerunented from #0 to RIF. After this, the branch falls and RTS returns to 
BASIC, Note thal the branch command, in spile of digassembling to three bytes, nane- 
theless occupies only two bytes of machine-code. AN branches have retutive addressing 
in the 6502, This is a fairly eimple concept, When the branch is instruction has been 
read by the chip, the program counter points just after it, to the next instruction - 
RTS here, The byte roltowing the branch is added te the proyram counter, and 4 jump 
made to the new address, if the brancl'a teal hucceeded, In the ecncple, counting back 
from RTS to TXA gives -7 bytes. This Ia $50 - 7 = 249 in 2'a complement form, ar FO. 


REE ea TIN IIE NE RMLs TI” cite A I Reo, aR SRR RT a RAS IE CN ET _— 


ee vip tw Bataan, Dra RSM a te Tal , 


oo 


a 


eR ig cicltin Ra 
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Example 4: Subroutines and comparisons, 


The previous machine-code example is a subroutine, which we called fram BASIC. 3t is 
also callable from machine-cods; the rautine which follows culls it 256 times, each time 
incrementing the address whieh, when indexed, determines the placing of each charact- 
er on the screen, Type in the code, retaining that of the previous example, which it 


uses: 
$0284 JSR $O027A ;CALL SUSROLTINE AT $O27A 


.M) 0284 20 7A 02 FE 7% O2 AD TE $0287 INC $O27E ; INCREMENT CONTENTS OF SOLTE 
“HO oQ2BC 02 C9 AG DO F3 GO xx xx $0264 LDA $O27E ;LOAD ACC'R WITH NEW CONTENTS 
$028D CMP #$A0) ,£QUAL TO #AQ YET? 

$028F BNE $0241 ;1F SOT, REPEAT LOOP 

$o291 RTS ;BUT IP £0, RETURN TO BASIC 


From BASIC, SYS #44 runs this. ($02e4 = 644 in decimal). It takes about ,3 of a second 
to return to HASIC; meanwhile the entire set of characters is printed on the screen 25 


{xx way be any value). 


70 
times, the starting points varying from S8CAU $20FF. then $8000-83GA40. Ikc O27£ has the 
same effect as poking J from BASIC when J is incremented from within the FOR ... NEXT 
loop. CMP ('CoMYare accumulator’), a Our example, compares FAQ with the contanis of 
the accumulator, which holds the incremented value im SO2TE. The branch orek oceurs 
until the pecumulator's contents equul &.\0, after a complete eycle of 256 increments. 
Note that it is eusier to test for equality with zero (as in the previous example}; 4 
comparison with 20 is not usually needed. Note that JSR. which is analogous ta GOSUB 
in BASIC, retuecns whan RTS is encountered. JSR actually means ‘Jump Saving Keturrt 
address', not ‘jump to subroutine’ as might be thought, The dranch instruction is a 
lite longer here, jumping 13 bytes buck; this is EF} in 2's- complement hexadecimal. 


Example 5: Decrementing and ceunting. 


If we call the previous routine 256 times (taking almost 4 minutes) the pattern of char- 
acters repeats. We can use the third and final register to count; this is the Y-register. 


(M0292 AO 00 20 84 02 B8 DO FA $0292 LbY #806 ;LOAD COUNTER 
.M O29A 60 xx mx KX XM XA EX XX 30294 .5R $0264 ;CALL PREVIOUS SUBROUTINE 
$0297 DEY ;DECRFKENT COUNTER 
(xx may be 47 tue). ‘7 
y be any value} $0208 BNE $0264 ; BRANCH IF COUNTER NON-ZERO 
$029A RTS <BACK TO BASIC 


5YS 658 sets this going. Note that the Stop Key will have no effect, since this works 
in BASIC onty by specially being tested before the execution of cach statement. ¥ is 
very similar to X, #lthough there gre sonc differences in indexed addressing: modus, 
which are asymmetrically distributed between X and Y. Decrementing, when used to 
count, is very similar to incrementing, but is often superior from the programming 
point of view, enabling a few byles to be saved. Like an increment, this comand 
passes directly between #0 and #FF. In the example, therefore, the value of Y within 
the loop is #0, #EF, FE, #FD, ..., 4. 


Example 6: Simple program with BASIC driver to [cok at CBM's memary - 


The machine-code subroutine, which we shall call from e BASIC program, moyes 255 
bytes of memory from seme portion of the CHM to the screon. (Note that the originals 
ace not altered in any way by the prowess of being reud). The BASIC progrum loops 
until Stopped; any keypress cuuses the 256 bytes following those currently on the 
screen to be displayed - except the comma, wiieh moves back, Any other key may be 
used instuad of the comma - sev line 10030. Put the keyboard inte lower-case mode to 
make strings, BASIC keywords in ROM, etc., readable. 


.M 027A AZ GO BD 00 CO 9D GO BO $0274 LDX #$00 

M0282 E4 DO ¥7 6O xx xx xx x8 $027C LDA 3C000,X ;LOAD ACC‘R FROM INDEXER 
$O27F STA $#900,X ;ADDRESS & SAVE IT 
$0282 INK 

$0283 BNE $027C 

$0285 RIS 


{xx may be any value). 


A simple BASIC progrem is this: 


19000 Lel92 + REM THI CORRESPONDS TO $CO OF $CU00; IT COULD BE INPUT AS A HEX NUMBER 
19010 POKZ 834,L: SYS 634 DREM DISPLAY 256 SYTES : 
1625 GET 43: TF X$<"" GGT) 10020 HEM WAIT FOR KETPRESS 

19630 IF X$:-"," THEN L=L-2 ZREM LF SPECIAL CHARACTER, REDUCE ADDRESS EY 2 
{NO4N Label, GUIO 10910 ‘REM INCHERENT ADDREYS: DISPLAY BYTES ETC. 


~, 
Tens 
Sets: Se arcevee te mmr amr ners Tt re TM PR ES ge, RN EAT RA HE EEN ORE, IW MO PMA SET 
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CHAPTER tt: PROGRAMMING THE 6502 MICROPROCESSOR 








43.1) Hardware features of the 6502. 
This section deala with the following topics: 


11.1.1 Addressing modes 11.1.2 The status register; NYBDIZC flags 
14.1.3 The program counter, zero-page, and stack 

Vi.t,4 Hardware vectors In the 6502: NMi, RESET, and [RQ 

14.1.5 Instructions and epcodes 


Note that Chapter 12 has a comprehensive guide to the 6502, prefaced with a table 
which indicates the meanings of the standard mnemonics. The appendices include a 
comprehensive set of tables of reference on the 6502. 


11.1,t Addressing modes, The 6502 has 12 or 13 addressing modes, depending on how 
they “are counted, Most of them am: quite easy to understand; a few are difficult. Let's 
first consider huw addressing modes are built into the chip. We've seen, in the ele- 
mentary examples of the previous chapter how an instruction may be followed by one 
or two bytes, or stand on its own, This is inescapable with this chip: no command 
extunds, in totr!, over more than three bytes, Now suppose an Instruction is encount- 
ered while @ program runs, and assume it to be @ three-byte instruction. [t might 
appear like this: «ax 00 80, referring tn the address $4000. Without knowledge of 
the precise fnstruction, however, it is impossible to state what addressing mode is in 
use: ag the previous chapter showed, xx -AD loads the accumulator with the contents 
of $€000; xx-RD luads it from $P000,%. So the instruction has, implicit within it, an 
addressing wode; and in fact this determines whether tae total instruction is 1,2. or 3 
bytes lung, and the pcesition at which the neat instruction is deemed ta begin. Note 
thet all addressing masses but one deal in memory locations; typically, the contents of 
some focution may be added to the contents of another, and compared with the contents 
of # third. Only 'immediate' mode addressing loads an explicit value, This rather ab- 
stract property of processors takes some time to grasp. Now we can exariine each mode 
in turn, For convenience, we can divide instructions into those of length 1,2, und 3 
bytes: 


t-byte instructions have no reference to either address or cata, end therefore eper- 
ate only on hardware features within the chip Itself. In a sense, the phrase 'address- 
ing mode’ doesn't apply at all, but for consistency these are descrited as possessing 
‘implied addressiitg’. Some of the flags, and seme stack operations, can be processed 
by these commands, as we'll sce in the next sections. The aceumulator can also be 
shifted or rotated bit by bit with a single-byte instruction; this is somctines disting- 
uished as 'Accumutator addressing’. 


2-byte instructions consist of an instruction fullowed by a single byte. If this byte ds 
treated as data, the fastruction uses ‘Immediate mode'. This Is usually indicated by @ 
hash symbol (#) befure the data; we had examples in the elementary programs ef the 
last chapter, for exampie LOA #$00 and LDx #soo, Apart fram loading one of the three 
registers with a value, this addressing mode is used in arithmetic operations, logical 
operations, and comparisons, 

All other 2-byte instructions refer to addresses, not data, There ere six differ- 
ent types, We have already vsed branches in the previous chupter, Their addressing 18 
usually called ‘Relative’, because off its use of an offset, which, in the 6502, confides 
the maximum range revchable by @ branch to a backward distance of 128 and a forward 
distance of 127 bytes. 

The remaining five 2-byte modes all use zero-page addressing. The zero-page is 
net 8 feature of the chip Itself; it is tha seetion of RAM (or ROM) which fs wired to 
eddresses $9000 - S00FF. However, the chip has the fuellity of enntling the most sig- 
nificant byte, of zero, ta be ignored, se that, for example, LDA $44 can ba written in 
place of ns $0934. Thia saves a byte, whieh in tura shortens progruns and faqrenwt 
thelr speed.*For this ressaon, the first 296 bytes are upuatly in great demand in 5502 





“The appendices Include a quick-retarance chart of 9502 addfrenaing-~moden' timing whien 
condenseé the information an timing provided by Che manufoecturers of tha chis. The KUS 
manuals on the chip have examplea to shew how the timlay ia determined ty the soparate 
eub-ingtructiona carries out al naeh clockcgyole, Yor our purnvern it is protakly 

eufficient lo nate that tang, complea fastructiois apa aAlowee than wbort staple onaa. 
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programs, 30 that machine-code routines which coexist with RASIC must be caceful to 
take into acvount BASIC's use of these locations. The five types of addressing are 
sty ese examples: a ; 
sry a tocage, This is the sitaplest type: LDA $55 (AS 5) eee 
with the contents af address $55, $55 may hold any value from #0 to rriee wi 
difference between this and the immediate mode instruction LDA #$35 (ao : irs 
loads the value #45 into the aceumulator, and has no connection with ee ae dase 
(ii) Zero page indexed by X. LDA $A0,X (BS AO) lords the ea rae eae 
$A0 plus the contents of the K-register at the time the instruction + can ene 
that the total of $46+X is itself treated as a zero page eddress; if iy api . 
it is ignored. If X holds 460, AQ+GG is treated as 0, not §0100, ond the co 
os B luaded into A. 
ae eo page indexed by Y. This is exactly analogous to the tthe See 
the chip is designed so thet Gly two commands can use this mode. vie aoe. eats 
liv} Indexed indirect. An exemple of this type 1s: LDA baat bs Se ahead 
brackets are a convention, which indicates that A is loaded from an in bh a Bhs 
Thet Is, two bytes point to the address from which the data is taken. Le — A 
for the moment that N cantains #0, to simplify matters. In effeet, we Bow eeere 
LDA (800) , singe the indexing effect of X is zero. Suppose the start 9 e BP 
is Hke this: 
O01 80 S4 G2 xx Xn KY KR. : : 
Now, Pe tea0} joads A from the address it finda in ($00), which x $8001. So eee 
instriction, in this instance, has the same effect as LDA $8001. In aoe Bure aoe vee 
addressing like this is not available on the 6502; ‘indexed indirect ad pinkie. Leen , 
name implies, allows indexing of the indirect address. Thus, if Xx a fess) at heh 
#2, then LbA (S00,%) has the effeet of loading A from the indirect ad Sea sae . 
or ($82). in effect, therefore, with the figures above, LUA $0284 is BecrUte aa ae 
command is useful (#} wren X-#0, as pure indirect addressing of ‘ne pirate, Hf 
when a table of pointers exists in the cL Ao phe BASIC pointers to the 3 
| nd ite variables, provide an example, ; 
sear ane is again eueigoteutal with respect to the X and ¥ registers; $e 
in Chanter 12 for scme comment on this. : -_— 
STY se liditent Juxed. An exainple of this type 15; LDA ($2A),¥ re res ie te 
the jetter mode. Lhe brackets indicate indirect addressing: if Y holds #0, getter! 
identical to that obtaine? when X holds #6 and Lha ($2A,X) is executed. Apar oe 
this special case, however, this mode is post-indexed by Y; that is, mbna 4 
ress is calculated, ‘here ¥ is added, amd the resulting address is the pear ° nS fs 
processing. Tu show haw this works, cansidtr the data shown above, : sees 
Dytes at (he very start of RAM. Now, baa ($00),¥ loads from aaers Pi re A C. 
bytes from $8001 to $4100 can all be accessed, depending om Y's va ae me on s 
some graphics exat:ples whien use this mode. See for example the routine to pik 
verticu! bars, histagram- fashion, in section 9.3. 


ians i sj instruction followed by & 2-byte 
byte instructions in the 6492 always consist of an ins u e P ; 
adeoas (Since the eceumulator, for exampie, is . &bit register, "LDA #$1234 makes 

3 : i f the addreas: 
no sense). There are four interpretations of t ; y de 

Gy abemite, This mode {a a simple reference to a 2-byte addresa, as in: 

pe LDA $0012. 3 . 

Gi) Absotute, induxed by X. The contents of X are added to the i bea te 
five the avlual refergieed eaddresa, Thus, If X holds #$50, LDA $8000,X sae on ‘es 
aceumulator frum $4050. As with ecero-pnge Indexing, the maximum value canno re 
the legitimate: range, sv (DA SFFFO,X when X holds #$11 lords the accumulator from 
$0001, not from the noe-existent $1N001. 

Git) ABAtste: indexed by Y. This Is exactly analogous to the previous ae 

fiy) Absolute Idearect, The 6502 has one instruction only with this mode, nan y 
IMP, An indirect fuup tranefers the program's flow of contro! to a hew deena alpen 
ig Jound from the contests of the address pointed to, by the indirect commun, ae 
exemple fs perhaps in arder here: aJuP ($0000) with the zero page ae ie ve oe 
before has the samy effect as JMP ¢B0UL, and JMP (20001) jtiinps ta $448 , and se an 
Tria commund ia unefia when a table of addresses exists ino block, Bee ee FOC 
tots at the top of HAM, without JMI nommands between the addresses. the RESET “" 
vector at fEEFE) ene Mn called by Jar ¢$PFrcy irrespective of BASIC ROM, Tables wit 
PP, the kernel Dor ecsaunpia, doa not reed abla. 


















ri ceocintige pei wanna see 
Le ee mR EN A WT GTI? WI ae aime 


“cual 1S Sabbah tincame case 


it: Progromming the 6702 


Progromming the PET/CBM -312- 
11.1.2 The status register and N.V,8,D,t,2 and ¢ flags 





Processor status register', recorded as 'SR' by the PET/CBM 
monitor, 1s an 68-bit register within the chip containing seven status bits or "fagta?. 
The eighth bit, Lit 5 in fact, is not used, and is fixed at 1, The flags are intimately 
reiated to the chip's operation, st least three being in & position in the register which 
is directly refuted to their function. A chart in the appendices enables a Status reg- 
ister to be separated into its individual bits; from it, an SR of Ad (say) con be imn- 
ediately recognized as having its & and I flags on, and its other fings off. Hefore we 
examine each fing's purpose, it is important to make clear the idea that the ilngs do 
not change uniess a comand explicitly alters them; the decimal (D) bit for example 
typically remains off throughout the entire operation of all the programs which a CBM 
runs. The appendices have a doubic-page tatile of opcodes, which includes a list of 
flags, those which are allured by e@ command belng marked. All the blank spaces in 
this part of the table mark fags which are left unchanged, LDA alters both the N and 
Z flags, but no others, for example. Where a fieg is marked, a '1' or '0' implies that 
the command explicitly set» thiy value in the fieg. 'CLD' for exampls 'CLears the Dec- 
imal' flag; the flag is set to 0, irrespective of its value before. The flags marked as 
'N''V''Z? and so on muy be set in either direction, depending on the result of the 
processing. LDA sets the '2' or ‘Zero’ flag true when the accumulator loads the value 
of zero, and 30 on, 


The 'N', 'Negative' flag {bit 7 of SR) usually holds bit 7 of the result of ai: operat- 
ion, or of an intermediate result, and can be pictuced ag a direct copy of bit 7 into 
the status register. LDA #$D3 loads 403 into A, and is a command which affects N. 
Since D3 F 110i 0011 in bit terms, with bit 7 high, the N flag is turned on by the 
instruction. The word ‘negative’ is based on the 2's complement idea: where this is in 
use, N = 1 shows a negative, and N= Oa positive, number, [n other cases the flag 
may be used in A convertionatised sense: hardware may bo wired to bit 7, and BME 
end BPL (Branch on Minus and Branch on Plus) used te detect whether bit 7 is high 
or low. See BM{ and BPL in Chapter 12. These branches depend on the state of Ni 
when on, BMI is taken; when off, BPL. So 'BPL' really means ‘branch if bit 7 is low', 
or 'branch if zero or positive’. 


The 'V', ‘interna! oVerfiow' flag (bit 6 of SR) is probably the least-used 6502 flag, 
because of the infrequent use of 2’s cumploincnt arithmetic outside the chip's own 
branch istructions. See the entry under BYC in Chapter 12. V is altered by only five 
instructions, including eddition fADC) and subtraction (SUC). 


The 'B’, ‘Break! flag (bit 4 of SR} is usually set only on BRK and when the SR is 
examined after having been pushed on the stack. Its purpose is to enable a BRK 
instruction to be distinguished from an interrupt, since both jump to the same address. 
Section 11.1.4 explains the hardware vectors on the 6502. 


The 'D', ‘Decimal caiculation mode flag (bit 3 of SR} changes the mode of operation 
of the chip from hexadecimal arithmetic to ‘BCL or 'binary-coded decimnl’. Seo SED in 
Chapter 12. When bit 3 of the stutus register is on, the effect on addition is to add 
6 to the low nybble if its result exceeds 9, and to add 6 to the high nybble if that 
result exceeded 9. When this bit is set - see SYS in Chapter 4 for an example - the 
normal arithmetic operations of the PET become confused, For this reason the built-in 
monitor takes the precaulion to clear the decimal flug. 


The ‘'I', “interrupt disable’ flag (bit 2 of SR) prevents the interrupt request line from 
causing the 6502 to service an interrupt, when it ig on, When off, any interrupt which 
uses the [RQ line will cause an interrupt, us explained in 11.1.4. In tis way, the 
program can be made to ignore intecrupts of thix sort until it ls ready to dem with 
them, See SEL and CL{ in Cyapter 12. The CRM uses a reguiar interrupt to read the 
keyboard. (f this is redirected to a new program, it may de necessary to set the dis- 
able Mag to ensure that the interrupe le not itself Interrupted. 


The '2', ‘Zero result’ flag (bit 1 of SR} ls act by most of the Instructions which set 
N, instead of repistering the result ina wlegle bit, % {in effect logiculty ORs together 
all the bits of a result; if thir procens gives # value of zere, ihe ZA bit ix aet, te anew 
a zero result; otherwito, when @ is off, the renult was fon: zere, The notes te BEQ 
and BNE jn Chapter 12 expand on this, 


The 'C', ‘Corry! flag (bit O of SR) is prinarlly 
where Jts function ly similar to tie carry wihileky 


The status register or 


of use in additions or subtractions. 
te used (or was und, bafore cheap 
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caiculators} to denote overflow from a column of figures ta a more significant column. 
BCC in Chapter 12 has notes on this flag. ana an example involving addition; CLC, 
SFC, and BCS are other commands involving this flag. 
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i1.1.3 The program counter, zero-page, and stack, The program-counter is a pair of 
S-bit registers, usually represented as PCL and PGH, connected to appear Hike a 16- 
bit register. This counter keeps a recoed of the current RAM or ROM location of the 
command being executed. Because of its 6-bit structure, updating in order to point to 
consecutive itens of data takes 2 clock cych.a, which Is why the fastest instructions 
take 2 cycles with this chup. The registers cun only be accessed indirectly; BRK or an 
interrupt causes the value to be saved, a3 dues JSR, where the ‘Save Return address’ 
refers to the program counter. RTS and RTL aocordingly both load their saved data 
into the program counter, su these commands can be used to load values directly into 
PC, CBM BASIC uses 'RTS' to jump to the addresses et which HASIC keywords are 
run; and the MLM uscs "RTI" to load the status register and the program counter when 
Gis run. The same effeet could be got - perhaps more easily ~ with a JMP instruct- 
ion, whose function is safely to reload PC with sume new value, 

The zero-puge, as we've seen in 11.1.4 o addressing, is the section of memory 
from $00 - $EF. The stock is a hardware feature of the chip, [t uses page i, i.e. $100 
- $IFE of RAM. (Note that memory is divided into 25u-byte pages. Some machine-code 
instructions tuke an extra clock cycle to compute branches and indexed addresses if 
the result happens ta cress the boundary of a paye). The stack is difficult to under 
stand, for several reasons. In the first place, the area of RAM from $0100 - SOIFF 
which holds the stack also doubles as normal RAM; it is not reserved for the stack 
alone. Secondly. bytes ‘pushed’ onto the stnek are added at the bottom of the present 
stack. Thirdiy, the stock pointer, in order ta be consistent, behaves in an appurentiy 
inconsistent way, operating differently when pulling than pushing. The stack pointer 
is another 8-bit register, which in the 6502 is always preceded by $01, and which 
keeps track of the current stack of dats. (ithe leading $01 foress the pointer into the 
range $0100 - $0}FF), Two conplementary pairs of instruetions exist on the 6502: 

PHA and PLA,and PH and PLP. Any of these instructions folluwed by the other member 
of the pair must leave the acevmulator or processor status flags unchanged. Because 
of this, the sequence store data/ updite pointer is used with a ‘push’, and the se 
quence update pointer/ load data with a ‘pull’, Chapter 12 his examples and comment 
under PHA, PHP, PLA, and PLP, Four other commands operate on the stuck automat 
ically: these ace JSR wed its complement RTS, ERK, and RTI. The stack pointer is 
@ecessible by transfer with the X-register only: TSX and TXS respectively transfer 
the current stack pointer tomitting $W1-) to X, and vice-versa. 


11.1.4 Hardware vectors In the 6502: NMI, RESET, and IRQ. The 6502 has, like 
many Microprocessors, & ‘Gluteh of Specially ruserved a «sea at the top of ROM. On . 
activation of the fon-ms.kable interrupt line, the reset line, or the interrupt request 
Une while the interrupt-disabie flag (CL) is off, the chip automatically sets the prog rai 
counter to the address in (FPFA). (FFFC), and (FFFE) respectively. The designer of 
the system has to cisure that suitable processing routines exist at the destination 
addresses, For exampic, BASIC 4 hae 

M4 PFYFA 49 FD 16 FD 42 ES xx xx, . 

so the effect of causing 9 mon-maskable interrupt can be investigated by disassembling 
from $FD49; the reset vequence (triggered at switeh-on) follows $FD16; and ordinary 
Maskable Interrupts are processed frou 6e442. These three vectors are the 6502's total 
conptement of spocial vectors; some chips have many more. Yhe BRK (BReaK') lnate- 
uction in fact shares the IRQ veetur, so a routine hag to be used ta work out whether 
4 ERK or interrupt caunzed the execution of the routine: this fu easy to find in the 
PETJCEM by di-assembiatg the machine-language frum (EFFE). [f the entry on the 
Stask hag its ARK flag 4B) set, an instruction ike SY¥8 4 iy assumed, and the monitor 
is entered; olherwias, the teguiar keyboard and sereen sarvielng routine ia entered, 
(Mote: the PEY, with BASIC {. ia different - see Chapter 15). An intercupt has a 
imiiur efiect to WRK, its that dt pushes the program counter and statis revisler otto 
ack, (But not A&, and Yr. fn this way. RTT (ReSure fran Intercuje€) era con: 
Sogeention of the iiterrapled routine when the inlerrayHd bas been serviced. For 








tins 
thiy ressan, BRK and YL respertively push and pull the swuae data on the stack, and 


fe eapry eut their opecationy in the opposite: patiay from oneh other. 

Yhe NM{ vector tavhich i: usabbe in BASIC 21) [x sometimes used ta slipply a 
reget awilth: lo the CHM, su that fafiatte doops tn machine cade can be aborted, See 
wollen BY, The RESED vector ia neif oxplanntory ; IM? CEFFC) cally it, and can be 
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ogrammning the PET/C8M 
od to erase a program after it has been used, for instance, 1HQ is used in the PET 
nl CBM to sean the keyboard, the frequency depending on the VDU screen, Setting 
¢ interrupt disable flag (with SEI) turns this off indefinitely. In process-control 


‘stems, most interrupts use IRQ, and cen be temporurily ignored by disabling the 
rvicing routines; the NMI is reserved for emergency use BS & rule. The pins on the 
02 which correspond to the vectors ste pins 6, 40, and 4 regpectively . 
are 6502 instructions and opcodes. An opcode Coperation code'> is a mnemonic, 
tinided to make machine language Telntively easy ta reed. 6502 opeodes are all three 
tiers tong (unlike e.g. 280 opcodes) which makes for tidy assembler and dijsassemb- 
r listings. An alphabetical lis? cf opeodes im the next chapter explnins the workings 
‘each instruction. it is prefaced by 4 table to summurise the mnemonics’ meanings. 
n opecd? bears the same relation to machine-language thst 8 BASIC keyword dues to 
5 tokenised form. Just as 4 BASIC keyword is stored in one byte, but LISTee by a 
secint routine which expands it into a recopnisable word, so 8 machine-code instruct 
m occupies one byte only. and is converted into a threo-ietter opcode for the sake 
f readebilily, ALhough the oprodes ere standard, there is nothing to stop anyone 
siug their own, for example by ciodifying the BASIC program in the previous chap- 
ar, This muy in fact be helpful as @ learning aid, although it would be unorthadex, 
There are 55 opcodes, some with one uddressing modc. some with as many &@5 
ight. We can group them by function es Idlows: 


Add/ Subtract ADC (Add with cerry’) and SBC (Subtract borrowing carry') are 

the 6502's arithmetic functions. Both addition and subtraction are carried out on 
all 8 bits, using the carry flag (C) for overflow, 2's coupiement arithmetic is rot 
used,*but Mays are present which enuble it to be implemented. Binary-caded dec- 
imal (BCD) arithmetic is available if it's wanted. 

i Branches The 6502 has eight branches, all conditional on the status of a flag. 
tnd all having a single byte 2's complement offset, The instructions are: BCC & 
BUS. BNE & BEQ, BPL & PMI, BYC a UVS, and the brunch is taken if the C, Z, 
N, and V flag is offon respectively. 

ti ‘Break! BRK causes an unconditional jump to (FEFE}, having first suved 
both bytes of the program counter and the slutus register on the stack. 

v Compurisons CPX, CPY, and CMP enable X, Y, and A to be compared with data 


or with memory contents. The date or memory is subtracted from X. ¥, or A and | 
N, Z, and © are set, soa comparison | 
| 





flags are set, without storing the resvill. 

may be followed by any uranch (except BVC or RVS}) to test the comparison. 

LDA, LUX, or LDY; it can 
be stored in RAM by STA, STX, or STY. These few commands are extended in 
dower dy being equipped with a lurge number of addressing modes. 

vi Decrements/ increments aluer X, Y, or memory by gubtraciing/ adding 1 bit, set- 
ting SN and Z. The instructions are DEX, DEY, DEC wad INK, NY, INC. 

vii Flaq_clear/ set enable sone flags to be altered at will: CLE, CLI, CLI, 
clear flegs C, OD, C, and ¥; SEC, SED, and SE) sct flags C, UL, and I, 

viii Jumps IMP acts like GOTO in BASIC, JSR acts like COSUB, with RTS the 
equivalent of RETURN. JSR srves Qecurrent sddrcss on the stack, 

AND, FOR (‘Exclusive or‘) and OWA (‘inclusive or’) perform 

retaining the 


vy Pata_transfers Data can be loaded from RAM or ROM by 


and CLY 


Ix Logical, operations 
binary loyical operations on the Accumulator aad date or memory, 
regult in A, and setting N and Z. WIT sets 3 flags. 

x Ng operation NOP dows nothing 

xi Return RIS returns te the instruction following JSR by jumping to the 
addresa currently on tha sack + ft, RT! jumps to the address vn the stack and aise 
loads the status register from the aluck. 

xl Rotate/ shift ROF nud KOR act on the Accumulator and the C flay (a 9-bit rot- 
ation). ASL CAsithmetic shift left") and LSR (Logical shilt right’) also involve A 
and C, but do not rotute C, so that vit GO with AST nad bit T witht LOR are always 
get to zero. Flnge N, 4, & C ra net. 

xili Stack operations are VHA. PHP, PLA, aud PLP. 

the slick, but BRK, ISR, RTS, and RTE also wee the stnck. 

the slack pointer ta te Erte / sek reapoetividy . 

Transfers between registers Six instructions nilaw tran. ferd between any two neigtr 

WAY, TAX & TXA, TS & TSX, 


Theos are explicit Gperntions oF 
TSX antl UXS allow 


xiv 
bourn of ¥,A.X, and 3. the opcodes are TYA & 


*ror example, CLO/ LUA #307 ADC #60 Leuvew A hotding MAG, which te Hbvioiely Hol & 
negetive number, However, the reaulta ero cunsintent with 2'a compinment arittaatts; 
in this case, tne M ting signale overflow Inte the sign bls. 


ELST: ET HIS Se RTE CeO aS TRE ERE RS ORIN me mE NN sectheme tg PTO awe 


co Uda ae 8 BE A. 
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14.2 Software methods using the €502. 
This section deals with the following topics: 


41.2.2 Decrementing 2 bytes 

11.2.4 Subtracting ?-byte pairs 

11.2.6 Division of 2 bytes by 4 single byte 
11.2.7 Comparing 2 byte pairs {1.2.8 Negation by 2's complement 

31.2.9 Other 2 byte operations 11.27.18 Loops 

11.72.11 Saving and restoring zero-page 11.32.12 Wemory-moving several pages 

11.2,13 Using shift and rotate commands!1.2.78 dunp tables, date tables, address labler 
11.27.35 Random numbers $1.2.16 Adtcessing modes 

1t.2.17 Testing for range of data 11.2,18 Using subroutines 


11.2.1 Inerementing 2 bytes 
11.2.3 Adding 2-byte prirs 
1t.2.5 Multiplying single bytes 


11.2.1. Incrementing 2 bytes: The best method is 


IKC LOBYTE 

BKE +2 ot +3; 

INC BIAYTE 
where the more significant by'te is incremented only if the low byte has just been in- 
eremented [rom #FF to #9. Note that a branch alter INC HIBYTE can be put in ta test 
for the transition from FFF to 0000, if this is importart. 


depending on position in RAM of hibyte 


14,2.2 Decrementing 2 bytes. There is no unique test for 4 decrement from #9 to #FF 
go this i less simple thas incrementing two bytes: 





LpA LOBYTE 
BNE +2 or td 
PEC ELBYTE 
DEC LOBYTE 


DKC HIBYTE may be replaced by LDA HIBYTE/ RRQ EXIT/ DRL RISYTE 
go tu EXIT when the two bytes hold #9000. 


11,2. 3 Adding 2-byte pairs. The carry bit (C) ts used to carry from the low to the 
high byte; i€ tne carry b.i 1s set on exit from the routine, overfiow has teken place 
from the high byte; ie. the result is too large for 16 bits. 


if it is required to 


cLe e.g. CLE 

LDA LO} LDA $24 
ADC LO? anc $61 
STA LOZ STA 901 
LpA BIL LDA $28 
Ape Biz ALC $02 
STA HI2 STA 302 


Note that an addition lewvcs Ure result in the accumulator; it inust therefore be stored 
in some way if it is ta de kept. In the exumple, the 16 bits made up of Hil end LOL 
are added to the {6 bits of Hi2 and LO2; the result is stored in HI2 and EO2, tut 
could equally well be stored in any other locations. The exauple with numerals adds 
the contents of (S$2A) to those of ($01), leaving the result in ($01), For instance. if 
$24 holds #34 aril $21 hol-is FAB, ($2A) contains the 16-bit veluc #AB34. And if $ot 
holds aFF and $92 holds wil, ($01) contains #itFF, The machine-code will feave ($2A) 


unaltered, Dut change ($01) to *#bD33. 


11,2.4 Subtracting: 2? byte pairs, The curry bit 19 usually aet before subtraction. if it 
ig cfenred on exit, the result is negative: ine first address heid dita of smaller value 
than the second. The gener reasoning {s alniiur to thut in the previns inztruction. 


SEC e.g. SEC 

LDA LOL LbA 82h 
fit LO? ADC $01 
fTA LOZ Ata $1 
LuA Wert LpaA $25 
EAD RI2 sane $93 
SPA HIS &TA $32 


te empire termine on comme cae reg ae ree a TR TT wr aes 


eer ee ae 








ions. It is possible to test a routine of this sort exhaustively, which is quite unusual. 
The routine is retocatable; the actual values given (i.e. in the middie of cassette buff- 
er #1) can of course be changed, but as the routine stands this BASIC program can 
demonstrate the machine-code: 


10 INPUT X,¥: POXE 136,%: POKE 137,¥: SYS 768: PRINT PEEK (136)+256*PEEK{iJ7) 


$0300 18 CLe 
$O3u1 «Ad 00 LDA #$00 
$0303 Az 08 LDX #$08 
$0305 6A ROR A 
3OW6 66 68 ROR $38 
$0308 90 03 BCC $030D 
$030A 18 Cre 
$0308 65 89 ADC 3a9 
$030D CA DEX 
$030F 10 FS PPL $0305 
$0310 85 B9 STA 389 
$6312 60 RTS 


This routine can be expected to take about 165 clock cycles en average - depending 
on the number of internal branches. So about 6000 multiplications of this type can be 
performed in one second. The method of operation relies on the ROR instruction, which 
ig used both to detect bits in $88 and to stare both bytes of the result. 
11.2.6 Division of 2 bytes by a single byte. The routine that follows has the con- 
verse effect to the Jatter routine. 6-bit Number is divided by an 8-bit number; the 
answer is assumed te be in the range 0-255, and this is normally taken cure of by the 
way the routine is used. The division is therefore a slight cheat: the multiply routine 
allows any pair of single-byte values (i.e 0- 255) to be multipliec, giving results from 
0 - 65025 (=FFOL), but division, although permitting any of these colculations to be 
performed in reverse, won't work correctly with (say) 65025 divided by 1. 

Three zcro-page bytes, ($48) for the numerator and $8A for the denominator, 
are assumed here, partly to make the routine easily workahic from BASIC, like this: 





40 INPUT X,¥: POKE 136,X-INT(X/256)*256; POKE 137,X/256: POKE 138,¥ 
20 SYS 768: PRINT “RESULT ="" PEEK(136) “ AND REMAINDER ="' PEEK(137) 


$0360 18 cLe 
$0301 A2 08 LOX #$08 
90203 AS af LDA $89 
$0305 24 44 ROL $68 
$0307 2A ROL A 
90308 BO 04 BCS $O30E 
30304 Ci BA CMP $AA 
H30C «90 03 BCC $0312 
QO30E ES BA BUC SBA 
9310 3h SEC 
$0311 CA DEX 
$0312 DO FL BNE 30:05 
$6514 24 88 ROL 986 
$0316 «88 89 STA $49 
$C31A 6D RTS 


The numerator Iw held in the analagous locutlona to tha multiply routing, eg the two 
mony be uaed tagether, Oo averaga, ou division taker about 185 mlerorecond4, about 
$400 por second, An exhaustive teat af this routine in muen slower than atibuna with 6 
multipilcation reutingy, sines all the remainders need te be checked. Notu Cant, ut the 
Atirt, the high byte of the numerater inust be less than tha deaomiaator, bucsudes an 
anawer texa than 256 la taken for vranted. For cach of aight foopn, the deoominator 

Ja doubled by a paler of leflward rutatlony. ard the numerntor subtracted, if thie ds 
powaible; If not, C ia clear, Tha low byte Js replaced by tho result, A jn the remaindur. 


Proqgromming the PET /C8M -316- 1: Progromming the 6502 

11.2.5 Multiplying single bytes. Multiplication and division are not functions present 
on the 6502, The followitig example uses two zero-page bytes only; the answer is left 
in the same two bytes, erasing the original values. The actuil zero page tocations are 
those for the NMI vector, which is unlikely to be used: if it is, switch to other locat- 
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t1.2.7 Comparing 2-byte pairs. The trick in this case is to avoid the comparison 
Larend TT coos orca ; 2 + . 
instructions, using SBC instead, which (unlike CMP &c) retains the result of subtrect- 
ion without only setting flags. This enabies.us to write a routine to test for equality 
as well as for the tess-than-or-equal-to condition which the carry bit tests, For 


example : 





SEC 

LDA 102 ;LOW BYTE OF THE FIRST ¥YALUE'S LOCATION 

SPC LO2 :LOW BYTE OF THE SECOND VALUE'S LOCATION 

STA TEMP ‘TEMPORARY STORE FOR RESULT (MAY BE ZERO) 

LPaA HI1 [HIGH BYTE OF THE FiRST VALUE’S LOCATION 

SBC HI2 ;RIGH BYTE OF THE SECOND VALUE'S LOCATION 
ORA TEMP ; RESULT ZERO (F BOTH ACC'H AND TEXP WERE ZERO 


If the contents at the first address equalled the contents of the second, the Zero flag 
(Z)} ig set. If the contents at the first were fess than those at the second, the Carry 
flag ig clear; and if the contents at the first address exceeded those at the second, C 
is set. So BEQ, BCC, and BCS respectively test for =,<, and >. 


11.2.8 Negation by 2's complement, The rule for 2's complement is ‘flip the bits and 
add i’. As we've seen, this ensures that a number and its conventionalised negative 
add to exactly zero, with overflow, a-bit numbers which add to 256 (=80100) are 2's 
complements; so are 16-bit bumbers adding to 65536 (=$10000). AN 8-bit number is 


easily 2's complemented: 





LDA NUMBER 

ROB #$7F THIS REVERSES EACH BIT 
cCLe 

ADC #$01 ;OR SEC/ ADC #$00 


If this procesa is performed twice on a number, the original number is obtained; there 
is no need to subtract { and then flip bits. The 16-bit equivalent involves EOR #SFF 
with both bytes, and then a 2-byte addition of #1. 


41.2.9 Other 2-byte operations. Since there are two registers in addition to the acc~- 
umulator, if Is often possible to write compact code using these to store the two bytes 
of a t6-bit address. For example, suppose ($2C) contains a pointer which we wish to 
decrement and store in ($0300), We can combine these objectiven like this: 


LDX $2A 
LDY §28 
DEX 

BNE LABEL 
DRY 

STX $0300 
BTY $0301 


LABEL 


11.2.10 Loops. lLoopa generally use either the X-regiater or Y-register as 9 counter, 
and often as an offset too, Three example programs below print the word "HELLO" at 
the top-teft of the screen. In each case, X is a counter, but ta also used as an offset 
to seleet one letter from the 5 bytes of ‘HELLO’ whieh are stored in RAM, [n the frat 
example, X la incremented (with INX), and needs CPX #95 to test for the end of the 
text. The second and third examples use DEX, which Is more elegant, since DEX rets 
the Z flag (on transition from #1 to #0) and also the N flag (on transition from #4 to 
*PP), BPL allows X to take the value #9; BNE does not, and the differences between 
the routines (n.g. X starting at #4 or #5, the use of 7FFF,X or 9600,X) aro the rasult 
of this. Possibly REL gives coda which In ensler to follow. 


$027A AZ 00 Lox #309 FO27A AZ OS ux #306 $N27AK Al O04 LUX #304 
FO27C «BD HK OZ LDA $O<Ka,X | 3027C =D 88 O2 LUA $02H5,K f oare BB AY O2 LDA $2R8,X 
S027" el OO #7 STA $4U00,% | $0u7¥ VD ¥F TF STA 97¥FT,X | sour 0D OG HO BTA $kU00,X 
$9242 «18 [Nz @0z82 CA ORX $022 CA DEX 

$5243 £O OS CPR #405 $0243 «po F? BNE 9027C $0283 10 FT BPL $027¢ 
$0245 DO FS BNS $027 $0265 80 RTS so2K, 40 RTS 


an7 «6G RTs wasn 40 as 4C . BYTE HELLO‘ $0and 48 45 40 BYTE 'KELLO’ 


$O2Hs 48 45 40 . BYTE ‘HELLO' 
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Section t1.2.14 has other methods for accessing tables of data, Nested loops can be 
written for the 6502; this is 4 delay 
loop, which uses all three registers 
(A,X, and Y¥) ag counters. When run 
fron BASIC, it shows how setting the 
interrupt disable flag turns off the 
CRM's internal BASIC clock. With the peda be ate 
addresses given here, $027¢ AS 00 LDA #300 

PRINT TL: SYS 634; PRINT TI $02z7zZ A200 LOX #900 
etyos equal or virtually Bus! values aneae nt 00 re #300 
‘or , spite of the delay, which 
is over a minute with the values as panes re re gin iia 
they appear in the program. (Loading $0286 DO FA BNE $0282 
A with other values alters the length $0288 69 01 ne 7301 
of the delay in direct proportion). $028A 0 F6 BNE $0282 
Note that the innermost loop runs 256 
times for each execution of the next moans Re ate 
loop, which in turn runs 256 tines as 
often as the outermost loop. To estimate 
the duration of such a loop, the outer 
foops can often be ignored (as they 
contribute less than 4% to the overall 
time). Reference to the timing charts shows that INX takes 2 clock cycies, and BNE 
with a successful branch, not across 4 page boundary, takes 4d cycles. So the total 
delay is about 256? * 5 /1000060 seconds, or 1 minute 24 seconds. 
11,2,ti Saving and restoring the zero-page. This is sometimes a useful trick, either 
to enable a long machine-code program to run in tandem with BASIC, or when using 
certain ROM routines which would otherwise change BASIC pointers. The TRACE 
routines in Chapter 5, for example, do this. The point about machine-code programs 
is that they are likely to be faster if the zero-page is used; in any case, a program 
may be written already, using these locations, and the effort of rewriting to fit CAM 
zero-page usage may not be worthwhile. The routines, one to gave in RAM, the other 
to restore, are simple enough; the only difficulty is to enaure the inviolability of the 
RAM area in which the zero-page is stored. Usually this will be in the top of RAM, 
below the acreen. 

SAVE 2ZRO-PAGE RESTORE ZFRO-PAGE 

LDX #$00 LOX #306 
LABEL LOA $G0,X% LABEL LDA STORE,X 

STA STORE, STA $00,X% 

INX INX 

BNE LABEL BNE LABEL 
11.2.12 Memory-move with several pages. The maximum range spanned by an 8 bit 
fegister, used for post-indexing, {s 256 bytea, so moving (say) 1K bytes normally 
means moving four batches of 256 bytes, with either a counter to run from 4 to 1 of 
(to 3 or whatever, or a test on the actusl addresses. Sectlon 11.2.16 has exampics 
of waya to do thin, and includes timlng comparisons. : 
14.2.13 Using shift and rotate commands. Shift instructions (ASL, LSR) are uneful 
whenever a byte In to be preaossed bitwise. After ahifting, the Carry Nag holds the 
laiwst bit to be shifted, so BCU or BCS processen the routing appropriste to a high 
or low bit respectively, In Chapter 14, @ VIA pregeam displays the contents of all 16 
rugistern iy thix chip, In bit form, using this method. Routines 10 convert paralloi 
data to sorlal {o.g. RS292 output are Input routines) typienily load the byt inte A, j 
then afift it & times, sending dadivicual bite serully down tha connecting wien, with a r 
few othur bits far parity, rte. Rotations involve 9 Lita, Including C. and #9 muy be 
used to Inspect bite while evontuclly returning a location to its ariyginal condition, or, 
more subtly, entering rome new, dependent value; the routines in 11.2.6 and 11.2.8 
for muttiplicntion and diviston en this, Hotations involving A are much faster than 
thoaa operating on memory locations, so lt Ix good practices ty work an A where ponraq 
ible, for example in 16-bit calculations. On the next page Is a typlest calculation sub- | 
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routine. It shows how a process of 


successive shifts and rotates left LDA $01; A holds Y-coordinate 
(which in effect multiply by 2) can ASL A yA holds 2*¥-coord. (0 - 48> 
be used in computations. Three ASL A jA holds 4*¥-coord, (0 ~ 96). C=O 
parameters are invoived: ADC $OL = ;A holds 5¢Y-coord. (@ - 126}. 

; ASL A yA holds 10*¥-courd. (0 - 240) 
$00 holds an X-coordinate {0 - 39), ASL A tA a 208Y-coord (0-480); overflow C 
$01 holds a ¥-coordinate (0 ~- 24), : 
and $02 holds #$2. ROL $02 3#4000 + overflow 

ASL A ;A = 40*Y-coord (0-960); overflow c 

The object is to set up o pointer ROL $03 7#8000 + overflas 
to the Xth column of the Yth row STA $01 :($0L) holds #8000 + 40*¥-coordinate 


of a 40-column screen. This can be 

done with a table (and in fact it is 

faster with that method). However, 

the method demonstrated here cal- 

culates #8000 + 40*Y, putting the 

result in ($01}, so an instruction 

like LDY $00/ LDA ($01),¥ 

references the correct position on the screen. This is used In SET (see Chapter 5). 


11,2,1% Jump tables, data tables, and address. tables, Jump tables contain JMP in- 
structions and addresses. The point Is to provide a table of values which are either 
(i) easy to remember, or (ii) easy to program (the actual addresses to be used only 
being filled in later), or (iji) constant, even with different ROMs (say). BASIC 4 has 
such a table at E000 in the 30-column version. Ali BASICs have the ‘ketnel', so that 
JSR FFEE4 always ‘gets' a character, for example, even though FFE4 has different add- 
resses following JMP. Data tebles store ASCII data, arithmetic values, messages. and 
ao on. CBM BASIC for example has keywords stored in a table, and these are separ~ 
ated from each other by setting the high bit of the final letter of each keyword. The 
high bit is masked (by AND #7F) before printing, but the N flag determines the end 
of a keyword. A similar method is to store strings terminated by @ zero byte; this 
wastes one byte per string. but makes it easier to have strings of different lengths. 
A routine to print such a string looks ; 





something like this, assuming no string LDX #$00 
is longer than 255 characters (so K on LABEL LDA START,X ;START=START OF DATA TABLE | 
its own spans the whete length of it). BEQ EXIT 


Address tob/es are similar in purpose JSA PRINT ;USE STANDARD ROUTINE (S) 
to jump tables, but contain addresees INX ; ASSUMES X IS PRESERVED 
only, normally in 2-byte form with the BNE LABEL ;BRANCH ALWAYS TAKEN 

order reversed, without JMPs inter- EXIT sCONTINUR PROCESSING 
apersed, The beginning of CaM BASIC ; 

has several (very long) tables of this sort. Address tables in practice are tricky ta 
access. CHM BASIC has examples in which BASIC keywords’ addresses are Jumped to 
by pushing two bytes on the stack and performing the routine to get the next BASIC 
character, which ends RTS, and thus both londs the accumulator with the appropriate 
value and jumps to any required address. (liowever, the addrusaes are actually stored 
ag addresn-1, because RTS always increments the return address}, A similar process, 
using RT1, is used by the machine-language monilor; this atluws the statua reglster to 
be set, in addition to jumping to a specified oddreas. Thesa manoeuvres are necessary 
because this part of HASIC Is in ROM. From RAM, tables can be accessed by the 
indirect jump inatruction. This example 
assumes that the acddrevaeg are tebled 
wtarting at $8900, und that the X-reg- 
Inter centaina the olfyet from the start 
of $8060 of the desired address, Thht method is far easier then using the stack, Due 
has the drswhnek thet the indirect Jump command has a hug, which cnuses It to work 
wrongly if a page-boundary 4 cronsed, See the appendices ('Further anpects of the 
6502' on this}. Alno, th: table mayn’t begin at precisely $1000 er $C OU ar whatever, 
40 X may need ta be increased by aome waka, 


OR7A BTX O2Z7E ;X ASHUWED TO BE OFFSET 
027D IMP (Bdxx)ixx ALTERED BY X 


19.2,1% Randont numbers, There wre kaveral waye to find pseude random numbers itt 
immehine code. In the Firat plice, tha BASIC routing may be aed; tha tia lta own 
aperdal ataenge Locatiare, and derives esch number tram the previews value ising this, 
uilens tho oegument t4 gera Ce, RNDOU) ). Tha ronult Ia In the range @ > 1s bt ts 
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forced into this range by putting the exponent to #40, So a random integer in the 
runge 0 - 256 can be generated by calling the routine, replacing its exponent by #88, 
and calling the routine to convert this to an integer. This, though thorough. is long; 
two alternatives follow: 

(1) Using the VIA counters. This method, like RND(0), is strictly dependent 
on time for the value it yields, so it it used within any regularly repeating code will 
show regularities. Nevertheless it is easy and quick to program: 


LDA $E844 ; TIMER 1 LOW 
EOR $E845 ; TIWER 1 HIGH 
SOR $E548 ; TIMER 2 LOW 
ZOR $ES49 ; TIMER 2 HIGH 


This leaves A with an 6-bit value, which for many purposes is ‘random’. 

(ii) Pseudo-random number calculations, We'll consider l-byte and 2-byte ran- 
dom numbers only; the principles are the same for larger byte numbers. The usual 
formula for pseudo-random numbers is a recurrence relation: 

Koay zat x, +¢ (mod =). 

If we set m=256 or 65536, the modulo condition, which means take the remainder after 
division by m, is automatically set by ignoring any overflow. A theorem of Gauss’s 
says that the maximum period of repetition is obteined when a=-4n + 1 and c is an odd 
number, That is, if we base our calculations on a single byte, a formula In which 'a' 
is a multiple of four, plus ome, and c is odd, will generate values which repeat with 
a cycle of length 256. The simplest case is 

x 








which is easily programmed: 


et 25 *x + 1 (mod 256) 
i LDA STORE ;LOAD LAST RANDOM NUMBER 
ASL A ;DOUBLE IT {IGNORING OVERFLOW) 
ASL A ; QUADRUPLE (IGNORING OVEAFLOW} 
SEC ;THIS WILL ADD 1 


ADC STORE ; FIVE TIMES NUMBER + 1 
STA STORE ;SAYE NEW RANDOM NUMBER 


This gives 0,1,6,31, 156, 23,66, 75, 120,89, 190, 183, 148, 229, 122,99, 240,177,128, 79,146, ..- 
which, because of the small values (5 & 1) may give an obvious sequence of ascending 
values when the eced becomes low (e.g. 2.11.56) but otherwise is probably sat!sfact- 
ory.* The process is similar with 16-bit numbers. We may use this easily- programmed 
retation: x = 257%, + 49981 (mod 62536}. 43981 is FARCD; other values are of 
course usnola?? If we rapresent the 16 bits by bytes HI and LO, this program gener- 
ates s sequence of pseudo-random numberas recurring every 65536 repetitions: 


CLC/ LDA LO/ ADC HI/ BTA HI/ CLC/ LOA #CB/ ADC LG/ STA LO/ LDA #AB/ ADC RI/ STA KI 


11.2.16 Addressing modes, To show how different addressing modes may be used to 
solvg a programming problent, consider the question of memory-moving 1024 bytes from 
6000 - 62FF inte the sereen area of a 40-column CBM, 8000 - 83I'F. Four acparate 
‘pages' of 256 bytes have to be moved. Section 9.5 haa a solution to this problem, In 
which X counts from 4 to 6, while a loop Involving indirect indexed addressing uses Y 
(chunging from #0 through to #0 again} takes care of each page, ft {fy possible to im 
prove on that routine; it cun be made bath sraller and about 13% faster, Using lta 
addresa locationa, we could use routine (a): 


(a) (6) 
L 0297 LDA (48),¥ b O207 LDA 63F?,¥ 


0299 STA (9A),¢% O20A STA GIFF,¥ 

0298 =INY Q29D IN 

az¢c BNE L O2UE BNE L 

O2Z9F DEC ad O2AG DEC O24 | DECAEMENTS IHIGH BYTE OF EACH 
G2aAG DEC BA G4AJ DEC O60  VANURENS IN LDA ANU BTA AUS,Y 
O2Aa MPL OL Q2AG BPL b 


which uses no counter, but relies Instead an the fuct that #49, degremented to W7F, 
lonves the N-flag clear, Routine {b) la similar bi ity eperatian hut mod flea nbawotute ad 
drowmes). It ds featur, alace tha commands within tha loop take leas thas. Hut it ia 
‘Note: 1t Ie a peculiarity of thie system of paoude-rand.a nuaber geapraltan that the 
vealuow Lt produces ere alwmya alternately add and even, fa addiliod, particular anriat 
exy have internal rescate of nubszerivs of aany hinds. 
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less easily relocated, since the program modifies Itself as it runs, and it is essential to 
modify exactly the right addresses, Program (a) hos the sdvantage of using the same 
zero-page locations to store its temporary data wherever the routine is put in memory. 
For the same reason, (b} cannot be used in ROM. 





Self-modifying code is occasionally used by the ac7O INC $77 
CBM; the example (right) is part of the GETCHR 0072 BNE $0076 
routine, which BASIC uses when scanning through 0074 «INC $78 
@ program (See Chapter i4 on this topic}. This 0076 LDA xxxx ;CURRENT ADDR. 
avoids the need to reserve an index for use with 0079 CONT INGE 
indirect addressing; it also means the routine has 
to he present in RAM, not ROM. 
11.2.17 Testing for the range of a byte of data. 
A mysterious eeistructlen paneiitien met with 19 LDA xxxx 
Plustrated (right) in a form which should make CMP #34 «=; BEANCR IF 
its operation fairly clear. Note that the first SEC cs L 3; = #3A 
is not necessary, since the carry flag is known SEC #00 - #39 
to be clear at that point, so SEC/ SBC #30 could SBC #30 ; +DO,D1,,,0,9 
be replaced by ssca2¥. However, it draws attent- SEC 
ion to the fact that #30 and #D0 are 2's complements. SBC #DO ;0-9 CLEAR C 
The point is that, on exit, the contents of A are L ; CONTINUE 
unchanged, but the carry flag is clear for values 
#30 - #39, and set for all other values. This range 
is of course the ASCII equivalent of numerals 0-9. 
As a variation on the theme, the second piece of LDA 4xxx 
code Is an ASCII-to-hex routine; this replaces CMP #3A 
#30 - #39 by #00 ~ #09, and #41 - #46 (ASCII for PHP 
A-F) by #0A - 40F, Note the temporary storage AND #0F ;REMOVE SIAITS 
of the status register, later recovered to test for PLP 
the status of C after the comparison. Bcc L 
ADC WOH ;ADDS 9,43 CH1 
L ; CONT [NUE 


11.2.18 Using subroutines. JSR and RTS are complementary instructions. designed 
to be easy to use and trouble-free; usually they perform perfectly well, the exceptions _ 
being caused by failure to appreciate the workings of the stack. See PHA,and 11.2.14, 
for details on loading the stack with a new address for RTS, and for RT}; und sce 
PLA on ‘popping! return addresses from the stuck, in the next chapter, Note that 
JSR xxxx/ RTS can always be replaced by IMP xxxx, saving two bytes from heing 
Pushed onto the stack. Conversely, however, JMP can be replaced by JSR / RTS only 
i? it includes RTS at some stage. 

ere Naither JSR nor RTS iieeeh A,X; or Y, or any of the fags, This means that 
flags, set within a aubruutine, can be tested 





on return. This is a valuable feature, which 7PS& LOX #06 
the specimen program fright} demonstratea. 7F60 CMP O100,X 
The sudroutine's function is to examine the 7763 BEQ 7F6R 
RAM area from $0100 - $010H for the presence 7¥6% = =INX 
of the character In A on entry. For example, Tra CPX #OC 
to test for #45 in the buffer (ASCII for EF), 7868 BNE 7F60 
7¥6A CLC 

LDA #43 776B RTS 

JGR 7PGE 

BCS FOUND 


cin be used. BCS appears because, on feturt, the curry flag Is clane if the character 
Wann'tt found: it is set if the cheracter was found, and moreover X bolls its position 
in relation to §0100, The INX eutstruction has been used because Ue subroutine bs 
letended to search the buffer from lel to right: in fact, this buffer liotd4 numernis an 
thay ape converted inte strings for autput to the #ereen or the printer, PRINT USING 
(Chapter §) uses this sateraullae, 

Although anbroutingd eon save a yreat deal uf memory space and make pre 
Kraan jorge rendable, (ey haves one fadmittedty smell) drawback in the 6902, wines In 
that they use only absolnte aditresning; educating, Chen la therefor dedhodus. Chapter 
14 has roumarks and mettada to help get yound this citfleully. 


os I SP SRT Toten ee ce Heater rm a 
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CHAPTER 12: ALPHABETIC REFERENCE TO 6502 OPCODES 





This chapter lists each opcode with full details on its use. Short demonstration pro- 
grams are provided for most opcodes, 
The following conventions have been adapted: 


rs is read ‘becomes’. For exumple, A:=X means that the value in A becomes that 
in X. 

x,@ and 1 show the effect on the status flags of an opcode. x means that the flag is 
set, bul its value may be 0 or 1. 0 and 1 represent flags which an opcode always 
sets to 0 and 1 respectively. All other flags are left unchanged. 

$ and 4 prefix hexadecimal and binary numbers; where these are omitted, a number is 
decimal, 

A,X, and Y are the accumulator and the two index registers X and Y. 

M means memory; this may be ROM in the case of load instructions. Note that 
# (immediate mode) loads from meinory immediately following the opcode. All other 
addressing modes load from elsewhere in memory. 

PSR or SK is the provessor status register. 

SP is the stack pointer. 

PC is the program counter: this is composed of two &-bit registers. PCL and PCH. 


The table below ia intended as a reminder or summary of opcode mnemonics on the 
6502, for readera who are not yet familiar with the opeodes or who have forgotten what 





they mean. 
GUIDE TO 6502 OPCODE MNEMONICS 
RO ee 
A accumutator/ arithmetic shift Ls left/ Jogical shift 
AQ add LD Joad accumulator, X, or ¥ 
AND logical AND Mio minus 


NE not equal ta zero 
NOP no operation 


B borrow the carry bit/ branch 
BIT bitwise instruction 


BRK break OR logicat OR 

Cc carry dit/ flag Is clear P processor status register 

Ct clear fiag PH push onto stack 

CMP compare accumulator PL pull from stack 

CP compare X or Y register R- right 

o decimal flag RO rotate byte 

CE decrement X or Y register RT return 

DEC decrement memory S$ flag set/ shift/ stack pointer/ 


E exclusive OR subroutine/ subtract 

EQ equal to zero SE set May 

t Interrupt flag ST store accumulator, X, or ¥ 
IN Increment X or ¥ register T transfer between ragisters 
INC increment memory location VV ooverfiow flag 


X X reglster 
YY register 


JMP jump te new address 
JSR fump ta subroutine, saving return 


. 


eee ‘ Fae hits Seals hae ead ~ ca 
germs MEL TY aa acd - — a ate nine th A ale EY I Bi OO YT LNA REE, IES FR 3 NPIS marr  # 
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ADC 


Add memory pius carry to the accumulator. Ass A+MtC 


INSTRUCTION | ADORESSING _ BYTES 
$61. ( 97 $0!70 0001) | ADC [zero peaex | 


$65 (101 %0110 0101) | ADC zero page 

$69 (105 40110 1001) | ADC # immediate 

$6D (109 $0110 1101) | ADC absolute 

$71 (413 Yo1t2 003) | ADC {zero page}, ¥ 
H 
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CYCLES 






















| 00 


$75 (437 BO1TT 0103) ADC zero page,X 
$79 (121 to1st 1091) ADC absolute, Y 
$70 (125 SOT1t 1101) ABC absolute, X 








*Add 1 if page boundary crossed 


eee a 7 
Flags: INY-8B8DBIZ¢!} 
om yb iES 


x x 

Operation: Adds together the current contents of the eccumulator, the byte 
referenced by the opcode, and the carry bit. If the result is too large for 
a single byte, C is set to 1. The internal overflow flag, V, is set if there 
is overfiew from bit 6 into the high bit, bit 7- If A holds zero (i.e. each 
bit = 0) the Z flag is set to 1; otherwise it is O.*(f bit 7 in A is 1, the WN 
flag is also set 1, to denote a ‘negative’ value in A. 





Uses: [3] Single, double and multiple byte additions. The carry bit automatically 

provides for overflow frum one byte to the next. For example; 

CLe ; ENSURES CARRY BIT [S$ 0 

LDA $4A + WE WISH TO ADD #$0A (10 DECIMAL) TO THE CONTENTS 

ADC #S0A ; OF ($4A}, 1.8. THE DOVBLE-BYTE ADDRESS WHERE $44 

STA $4A ; IS THE LOWBYTE AND $48 THE KIGH BYTE. 

LDA $48 

ADC #$00 ; ADDS THE CARRY O1T WHEHE APPLICABLE 

STA $48 ; RESULT MUST BE STORED, ELSE IT WILL REMAIN ONLY IN A, 
[2] Increasing or decreasing the accumulator; there is no ‘INC A’ opcode. 

BCS AWAY ; EXAMPLE ONLY. (WE KNOW CARRY BIT 19 CLEAR KOW). 

ADC #$01 ; INCREMENTS A; #0 BECOMES #1, #1 #2,..., #FF BECOMES WO. 

cLc ; ANOTHER EXAMPLE. CARRY BIT NOW OQ. 

ADC #$FF ; THIS SUATRACTS 1 PROM A AND SETS CARRY FLAG UNLESS A-O 
{3} In binary-coded decimal mode, obtained by setting D to 1, each nybble 
represents 0-9 and addition Is corrected tor thia basis. This aode is unused 
in CBM equipment at present. On switching on and on entry to the monitor, 
D is always cleared, so ADC is in hexadecimal made untess D is specifieatly 
set. This example adds 124 (decimal) to the contents of locations 0 and I, 
which are assumed to contain, in ascending order, 4 binary coded digits. 
Thus locations 9 and 1 contain, in BCD, 0- 9499. 

erp s BET THE DECIMAL FLAG 

CLC ; CLEAR CARRY FLAG 

LDA $1 : WE'VE ASSUMED THE BOD DATA 15 STORED IN NORMAL OANER, 

AnC #923 ; WITH LOW BYTES FOLLOWING HIGHER ONES, NOT 6502 ORDER 

BTA $01 ; ADD 23 DECIMAL 

LDA $00 

ane HI 5 ADD Of DECIMAL PLUS PONSIBLY CARRY BIT EQUIVALENT TO 100 

$ta yoo 

cLp ; CLEAR THE DECIMAL BIT, UNLESS MORE DECIMAL MATH NELDED 

Notes: {1 ]*In decimal made, the rero fIng dorsa't opernte normally with ADC 
because of the automatic correction (adding 6) which the 6502 curries out. 
Testing for a zere ceaull requires (for example) TAs BRQ ... or CaP #09/ 
Beq.... which Ix an exten aiep not required in hexndachnal arhthinetis. 
(2] The V flag te important Uf the 2x complement convention ig in uae, in 
which cass it tests whether the high bit means negative, or Intplles that thea 
addition han overflowed to bit 7, fn YCD, Zs complement Ip uouanhia. 
Re akg cae eae enka ene erate pny CR GYM A So folate A AE RR Re ERI TYR tm RRR, © to tS 8 er re 
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AND 


Logical AND of memory with the accumulator. A:-A AND M 
INSTRUCTION _ADDRESSING 


33 30010 0001) | AND (zero page, xX) 
37 20010 0101} | AND zero page 

41 20010 1001) | AND # immediate . 

45 $0010 1101) | AND absolute 

89 $0011 0001) AND (zero pagel,¥ | 
53 80011 0101) | AND zero page,X | 
57 2OOt1 1007) | AND absolute, ¥ I 
61 8001) t107) AND absolute, X 


*Add 3 if page boundary crossed 


Flags; INV-BODOIZC 
x ate 


Operation: Performs AND of the 6 bits currently in the accumulator and the 8 bits 
referenced by the opcode. See BASIC's AND command for a description of 
the truth table of AND. Essentiuliy, when both bits are l, the result is 1 
but if either or both bits are zero, the result is 0. (So the first bit AND : 
the second must be 1). The resulting byte is stored in A. If A now holds 0, 
j.e, ali its bits are zero, the Z fiag is set to 1; and if the high dit is set, 
i.e. bit 7 is 2, the ‘negative’ flag N is set to 1. Otherwise the flag is 6, 


Uses: [1] Masking‘ off unwanted bits (cp. ORA) typically to test for the existence 
of a few high bits, or to test that some bits are zero: 
LDA $£081,X ; LOADS ACCUMULATOR FROM A TABLE OF CODED VALUES. . 
AND #$3F i .. TURNS OFF BITS 6 AND 7, LEAVING ALPHABETIC ASCII. 


72: 6502 apcodes 

















LDA $E940 + LOADS ACCUKULATOR FROM VIA'S IEEE REGISTER + CASSETTE 
AND #$EF + MOTOR CONTROL. THEN TURNS OFF BIT 4 WITH Z1110 1111. 
STA $EA40 3 STORES RESULTING VALUE BACK IN REGISTER 


[2] AND #SPF RESETS FLAGS AS THOUGH LDA RAD JUST OCCURRED; 
AND #$00 HAS THE SAME EFFECT AS LDA #$00 


Shift memory or accumulator left one bit. (CH7 65 4321 oM0} 
INSTRUCTION ADDRESSING CYCLES 


$96 (6 30000 O170) | ASL zero page 
S0A { 10 40000 1010) ASL accumulator 
$0E ¢ 14 90000 1110) | ASL absolute 

$t6 ( 22 $001 6110) | ASL zero page, x 


$1E ¢ 30 $0001 1110) ASL absolute, X 
Flags: (NV - BOs eH 


































5 
2 
6 
6 
? 








Operation: Moves the contenta of memory or the accumulator left by one bit position 
moving 0 into the low bit, and the high bit Inte the curry flag, erasing tts 
current value, The carry bit therefore in set to 0 or 1 depending on bit 7 
previously being 0 or 1. Zand N ere set pccording to the rusuit: thua % 
cun be true (1) only If the location or A held #800 ac #$80 befora ASL. The 
N blt can only be net true if bit 6 was previously $, 


Uses: {1} Dowblen a byte (though not in deviinal made), If signed arithmetic is 
not belng ured the result cen safely rene values not exeueding 254, after 
which the carry must be token into account, often with ROL. Thls example 
Uses A froin @ to 127 to lond two bytes from a tohle of address Holnters: 

ASL As TAY/ LOA ADDHI,Y/ PHA/ LUA ADULO,Y/ PHA and stare them on tha: 
Stack. Anolller example: LDA $20; ASL AZ ADC $20 moltiplies the eonlent 
of $29 by three, provided thet it originally bull 4#5 decimal at moat, in thin 
vasa, the carry bit im automatically cleared by the shift, : 


[2] Toate a bit by moving it into % or N. pertiapa with « flag tn BASIC. Note 
that 4 ASLs move tho low nybble into the high nybule, 


. 


EAP TET PCE PETE TIE! AOI 4 NEAT REM NAR R C Me he Ae EI I CNA Myer rina ree I 
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BCC 


Branch if the carry bit is 0. PC:=PC + offset 
INSTRUCTION ADDRESSING 


if Al BYTES [CYCLES 
$90 (185 41601 0000) BCC relative 38 2" 


*Add 1 if branch occurs; add 1 more if the branch crasses a page 
Flags: [NV_- 8 DZ C| 
| ee ed 
Operation: If © holds 0, the byte following the opcode is added to the program 
counter, which is set to the following command. If © holds 1, the program 
counter is unaffected, The effect is to cause a jump to the offset address 
when C is ctear, 


Uses: {1} If the carry bit ia known to be clear, this command becomes effectively 
a ‘branch always’ instruction. So the Gag may be set in a purely signulling 
sense, with no significance other than to show that one of two conditions 
gpplies. For exemple, BASIC'’s commands toEND and STOP a program are 
almost identical, except that one command prints a message with a line- 
Number, and the other doesn’t. So: 


C763 HCC C768 ; CARRY BIT £S SET YOR STOP, CLEAA FOR END... 
C765 IMP C37E ; PRINT "“BHEAK IN LINENUMBER' MESSAGE 
C768 IMP C389 ; PRINT “READY" 


[2] Usually the test is concerned with the result of a previous operation 
which may or may not set the carry flag; this compare routine for 
instance: 
JSR GETCRAR ; LOAD THE ACCUMULATOR WITH A VALUE (DEVICE NO. , TRACK, SEC~ 
CUP #$0A TOR, OR WHATEVER). COMPARE WITH #04; THIS SETS C. 
BCC TO 0-9 ; BRANCH TO PROCESS THESE LOW VALUES: 
; CONTINUE HERE WITH HIGH VALUES, 10-255 DECIMAL. 
















ADC and SBC, the add and subtract operations, are obvious cundidates 
here, but occur less often with BCC than might be expected, because the 
value of the carry bit can often be taken care of by the mathematical routine 
without the need for branching. This example might be used in t-byle 
addition where anoverfiow warning is needed: 

CLE CLEAR FOR ADD 

LDA LOADD ACCEMLLATOR HOLDS CONTENTS OF THE LOWER BYTE. . 

ADC #LO ; .. ADDS THE LOWER BYTE VALUE 

STA LOADD ; AND STORES IT; C MAY BE O OR 1. 

LDA HIAD@ ; ACCUMULATOR HOLDS MORE SIGNIFICANT ADDRESS BYTE.. 


ADC #sKI : .. ADDS THE HIGHER BYTE VALUE 
STA HIADD ; AND STORES IT. AGAIN, C MAY BE O OR 1: 
BCC CONT ; EF IT'S CLEAR, TH ADUITION HAGN'T OVERFLOWED, 


JMP OVERPL ; 1F IT'S 1, PROCESS ACCORDINGLY; E.G, ERHOR INDICATION 


BCS 


Branch If the carry bit is 3. PC:=PC +offset If C=1 


INSTRUCTION — al ADORESSING | BYTES | CYCLES | 
$80 (476 Br0tf GOGO; | BCS relative oe 2A 


*Add 1 If branch occurs; add 1 more if branch crosses a page 

pe a sata. geet 

Flags: [N Y-BDIZC} 

Operation: Ideaticnl tes Nee, except that the branch is token if C2) and not O-4, 



























Uses: 14} ‘The uses are identical to thase of HOC; the choier between HOU nal 
BCS ata branen point depends on convetdence anty. Far example, sappus 
e herdwire port is te be read until bit Lle set te 0, this routlne: 


LOOP LOA PURT 
LOR A 
BH A 
WC LOOP ; 

is mare patural than one juvelving BEC, and easter lo read. 


, LOAD FROM HERE UNTIL uxxx xadx 


co Ce UN orn ARR EE EE AN eS EP SE RRS oT RRS A 
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BEQ 


Branch if zero flag is 5. 


INSTRUCTION __ DRESSING 
$F (240 1111 0000) { BEQ relative 


*Add 1 if branch occurs; add 1 more if branch crosses a page 


NV-BO1IZC 


PC:=PC +offset if Z=1 
ADORESSING | 













BYTES 
oo 





CYCLES 
7* 








Flags: 


Operation: if Z=1, the byte following the opcode is added, in 2's compfement arith- 
metic, to the program counter, which currently points to the next opecde. 
The effect ia to cause 4 jump. forward or beckward, up to & maximum of 
about #128, if the zero flag is set. IF 2:¢ the branch ts ignored. 


{1] The zero flag cannot be set directly (there is no 'SEZ"). But since it is 
very often set in the course of @ program, the usc of BEQ as an unconditional 
branch is common. This sort of thing may be used to make short routines 
relocetable, where the branch command isn't quite wide-ranging enough to 
permit all the branching that is needed 
within the routine to take place without an 
intermediate hop. This, of course, is not 
really recommended with large programs. 


Uses: 


LDA #$F4; SOME VALUE OR OTHER 
BEQ BACK; THESE TWO BRANCHES 
BEQ FwRD RELY ON Z=1 


[2] A common use is to end a loop, either when a counter is decremented 
ta zero, or because a zero byte is deliberately used asa terminator: 
LOOP LDA TABLE,X ; LOAD A WITH THE NEXT CHARACTER 
BEQ &X‘T ; EXIT LOOP WHEN ZERO BYTE FOUND 
ve. CONTINUE, £.G, STA OUTPUT,X/ INX/ 3NZ LOOP 


[3] BEQ is popular after comparisons because it's easy to use: 
JSR GETCHR/ CHP #$ZC/ BEQ Cota looks for a comma in BASIC. 


Notes: (1] When a result !s zero, the zero flag 2 is made ‘true’- i.e. 1. This point 
can confuse people. 'BEQ' is usually read ‘branch if equai to zero’ but when 
comparisons are being made it could be read ‘pranch if equal’, 


BIT 


Test memory bits. 
INSTRUCTION 


$247 ( 36 Foot 100) 
$2c { 34 $0010 1109) 


Flags: (NV - BOI ZC 
MT 


Z flag set on A ANDO M; N flag=M7; V flag=M6 
ADDRESSING _ BYTES | CYCLES 
| BIT zero page ae 3 

BIT adsolute 





















ME x 


Operation: BIT affects only three fiugs leaving registers ond data unchanged. 2 la sct 
on A AND M: if no bit of the memary {ocution and of A has a 1 In cach, then 
A AND M Is zero und 22. Also, bits 6 und 7 are copied from memory to YSN, 
(21) The d-byte, absolute addruss BIT is the only instruction regularly used 
LBA #900 Ag OD ; LDA #OD for uncenventionn! dixussembly from 4 non 
BiT $20A9 2C AD 20 ; LDA #20 atendard entry polit. The example loads A 
BIT $1DAS 2 A@ 1D; LDA #1D with Return, space, or fRIGET) depending 
on the entry point into the routine. 


[2) BIT with BMI/WPE or HVC/EVS tents Llis Tand &. This ta offer used 


Uses: 


Bit $0700 with PIA/VIA Joc.tions: see the TEER examples. The excmple 
far ERH oo here tusts location $07. with an error IndlenUon Wit holds a 
RIB negallve, $07 b: in facet uned te chork for type mlematches. 


ERR owe KAROR #FF denotes n string, #00 n numeric varlible, 


(3) This example stowa the AND frature in uae. CHRELO molds Hf no char 
LOA VALE aeter Is to be output, and #FE olherwine, Agauming the 

BIT CHAFLO accumulator halds a ngun-zere value, HIT leat whethar to 

REQ NGTOUT branch pant the oulput routine, while retaining A‘ value, 


ETAT yt ere SALLI MNT 2 TT I PETRI OLY: MEE EO OR BERT RE ee ae 


CN Re TRE A ay reg ee ne a a i ee ae 


we 
A en me RN Ee erie Sor A TREN ECE RE Se RE TA 
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BMI! 


Branch if the N flag is 1. 
INSTRUCTION ADORESSING 


JETIO BYTES {CYCLES 
$40 { 48 ¥6011 0000) BMI relative oe 2* 


*Add 1 if branch occurs; add 1 more if branch crosses a page 

Fiags: [NV - 60126} 

Operation; The program counter is incremented to point at the next opcode, and 
if N holds 1 the byte following the branch opcode is added to the program 
counter in 2's complement form. The effect is to force a jump to the new 
address. The maximum range of a branch is therefore about +128. When N 
holds 0 the branch command is ignored. 


{1] Testing the 'negative' bit of a location; for example: 
LOOP BIT $£840; BIT 7 IS CONNECTED TO DATA VALID SIGNAL.. 
BMI LOOP ; .. THIS LOOP WAITS UNTIL DAY IS 0, 


Like other flags, N may be used in a purely conventional sense. As an ex- 
ampte, consider BASIC's keyword tokens: these al! have values, in decimal, 
of 128 or more, which keeps keywords logically separate from other BASIC, 
and also permits instructions like this schematic branch: 
LDA NEXT ; LOAD NEXT CHR INTO ACCUMULATOR 
BMI TOKEN ; BRANCH TO PROCESS A KEYWORD 
+ OTHEAWISE, PROCESS DATA AND EXPRESSIONS 


Notes: [1] It's important to realise that the ‘minus’ in BMI refers only to the use 
of bit 7 to denote a negative number in 2'a complement arithmetic. It may be 
easier to think of this operation as ‘branch if the high bit is set'. BPL is 
exactly the opposite of BMI. Where one branches, the other does not. 


BNE 


Branch if Z is ¢. 
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PC:=PC + offset if N=1 























Uses: 


PC:=PC + offset if Z=6 








*Add t if branch occurs; add | more if branch crosses 


Flags: [hi V-BbDIZzC¢C 

Operation: BNE operates exactly like BEQ, except that the condition is opposite. 
if 2=0 the offset contained in the byte after BNE is added to the program 
counter, so the branch takes place. If Z=1 the branch ia ignored. 


[1] BNE may be used in unconditional branches in circumstances like those 
which apply to BEQ- ane note (1) on BEQ. 

{2] BNE is very often uaed in a loop in which a counter is being decrem- 
ented. This ta probably the casicst type of loop to write, although the 


Uses; 


LDX #$0A starting addrean of the loop'a data needs to be 

LOOP LDA TABLE, fixed with care, aa offset @ isn't executed by a 
JSR OUTPUT loop like this, The example prints ten characters 
DEX from 4 table, their offsets being 10,9,8, ...,2,1. 
BNE iQuP 


[3] BNE, Heke BEQ, 9 populace efter crinparivona: 
B4CO LDA $C1 
B4Ca CMP #942; IK IT 8? 
BAC4 DNE Bice 
BAC JMP SRB76 
HACY CMP wads, [8 IT H? 


Notes: {E} When a rewitt Gary, of DA) is nen-zero, the zero Meg “in med false, 
fee, set te O. This eno be confusing. "BNE! ly usually eead "branch tf not 
equal te zero’. The result of nm ecompariaqan t4 zero If poth byted are Wdenticatl, 
because one da subtracted from the othar, Henees the use of HNE aud FQ. 


Compuriaons like this can continue over 
many bytes of machina-cade. 


Rn eee ee ot EAR mR RE cana ee Poms te tk pea 
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BPL 


jranch If the N Mag is 0. PC:=PC + offset if N=¢ 


(NSTRUCTION ADDRESSING BYTES !| CYCLES 
"1 men “oo ria 


*add 1 if branch eccurs; add 1 more if branch crosses a page 


7 [A Gao 
“lags: [NV -BD ee 


dperation: BPL operates exactly like BMI, except that the condition is opposite. 
The drench is taken to the new address given by program counter plus 
offset if N-0. This means that if the result was positive or zero the branch 








$id ( 16 40001 0900} "| BPL relative 


is taken. = 
Jses; [1t) In testing the negative bit of a memory location. This code. for exampie 
LOOP LDA TESTLOCN waits until the accumulator holds a byte 
BPL LOOP with dit 7 on. Such a location must be 


hardware cotrolled, not just RAM. 


{2} Testing for the end of a loop where a counter is being decremented, and 
the counter's value 0 is needed. This simple loop prints 10 bytes to screen: 
Lox #509 ; X REGISTER WILL COUNT 9,8,7, ... ,1,0 
LOOP LDA BASE,% ; 'BASE‘ 19 THE STARTING ADDRESS OF THE 10 BYTES 
STA 8000,X ; CUM SCREEN STARTS AT $8000. (OTHER MACHINES DIFFER). 
DEX : DECREMENT X 
BPL LOOP ; BRANCH WHEN POSITIVE OR ZERO 


BRK 


Torce break. $:=PCH, SP:=SP-1, $:=PCL, SP:=SP-1, S:=PSR, SP:=SP-1, PC:=(FFFE) 
INSTRUCTION —_—si[| ADDRESSING _ BYTES [CYCLES 

$00 ( 0 40000 Ot00} BRK implied pee 7 
Flags: Yee Tze 


















1 x 





Operation: BRK is a forced interrupt, which saves its current position and status 
and jumps to a standard address. Note that (i) The program counter saved 
points to the BRK byte plus two (ike a branch), and {li) The processor 
status register on the stack hag flag B set to t. In CBM machines, the new 
address is shared by the IRQ service routine and generally with the 6502 
maskable interrupts always jump to ($FFFE); the break flag is a sort of 
designer's patch so that BRK can be recognized as different from other 
interrupts. 


Uses: [£} BRK con be used to puteh programs (as mentioned in Zaka' 6502 book), 
but thia requires (i} a change in the interrupt's vector, Le. 692) in RBASIC>1 
or (30219) in BASIC 1 and (ii} processing required by the program. Also & 
return, using? the stuck program counter and processor stietus, ia needed. 
This is sufficiently compicx not te be duae often. 


[2} With BASIC vectors left as on power-up, BRK causes BASIC to jump to 
the monitor, or ta locstion $0 in BASIC !, This is why SYS 1024 or S¥S 4 
may be used to enter the moniter. 1524 normally contilns a zero byte at the 
start of BASIC; 414 zero whenever quotes mode in nat set, e.g. wher In 
direct mode, On entering the moniter Ue date on the stack fs puiled off 
and displayed. The program counter is (for dame reason) decremented, 
alnce PC+2 Ig stored, Ihe nonitor addresé points at the byte after BK. 


ES LNT | ET I TT IEF TE Ae RE ERE Se 2 mg See rere pratense” 
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BVC 


Branch if the interna! overfiow flag (V) is 0. PC:=PC + offset if V=0 


INSTRUCTION ; ADDRESSING BYTES | CYCLES 
Sso {RO Yorot 0a) ahi ¥ 


BVC relative 
*Add 1 if branch occurs; add 1 more if branch crosses # page 


Flags: ve ores 


Operation: If V is clear, the byte following the opcode is added, as a two's 
complement number, to the program counter. set to point at the following 
instruction. The effect is to jump to a new address, which must be within 
a range of about +128 bytes. If V-1 the next instruction is processed and 
the branch ignored. 














Uses: [1] As @ ‘branch always’ instruction : 
CLy 
BYC LOAD 


{2] With signed arithmetic, to detect overflow from bit 6 inte bit 7, giving 
a@ apurious nepative bit. This is rather rarely used since the sign of a 
number can be held epart from the number, pechaps as #0 or REF, so that 
ordinary arithmetic can be used without the extra complication of the V bit. 
See the note for an expianation of V's derivation. 


LDA ADDI This routine adds two numbers, in 2's complement form; 
cle their range therefore is -128 to 127. Clearing ¥ is only 
(CLY) used in examples like [i]; unlike the carry bit C, it is 
ADC ADD? never added in to results, so clearing is not needed. 
BYC OK CLC js necessary; it may add in 1 to the result. 

JMP OVERFL 


[3] BIT copies a location's 6th bit into the processor status regisler, 50 
BYC or BVS can be used to test bit 4. For example, this routine: 


FiO3 BIT $840 waits until the hardware sets bit 6 of locxtion SE840 
F106 BYC $F103 equal to Ll. 


Notes: {Lf The Meaning of ¥. When using signed arithmetic, two numbers of 
opposite sign cannot overflow. The most extreme values, €.g. ~128+0, are 
always within the acceptable range. However, if the signs are the same, 
overfiow is possible. #56A + N$5H overflows: the result is not in the range 
-~124 to 127. We have: 20110 1010 + R0101 101% = $1100 O101. When the two 
leftmost bits ure %, each original number in positive; if in addition the 
result has bit 7 equal to 1, an overflow must have occurred. Similarly, two 
negative numbers with overflow behave tike thls: consider -100 aad -89, in 
decimal, When added, these overflow, since -189 is aut of the acecptable 
range for signed bytes. Now, +100 = #361 und +89 = A859. The negatives 
are therefor: -100 = #SYC and -89 - #$A7, We have: £1001 1100 + INTO ALLL 
= 30100 0011. The overflow shows Itself in cnuging two negative numbers 
to apparently add to 4 positive, V is thus gaiculuted by complementing the 
EOR of 2 negativebity, and ANDing the result with the EOK of the resuit's 
negative blt and ent the original number's negative bits. This Ix not #0 
complicated ny it might seam, 


BVS 


Branch If the internal overflow flay (V) is 1. PC: PC + affset if V=1 


INSTRUCTION | ADDRESSING. | BYTES | CYCLES 
STU {tt2 BOIS H9V0) BYS refative 3 2 


‘Add | if branch occurs, add 1 more if branch crosses @ page 
Flags: [w vo apsec} 


adh J 
Operation: Thin trauect is Idanitienl to BVO except that the tent logis lo deetde 
whether tae beaneh da taken In oppesity, See nntea on BYE, 


el en eh ae 
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CLC 


Clear the carry flag. C:=0 
INSTRUCTION 





ADDRESSING 





$ia ( 2% $000T 1000} | CLC implied 


Flags: A ~BDIze 
=| 


Operation: The carry flag is set 0. Ail other flags are unchanged. 


Uses: The carry bit is an automatically included feature in add and subtract 
commands (ADC and SBC), so that accurate calculntions require the flag 
to be in a known state. CLC is the usual preliminary to additions: 


CLE 

LDA #302 After CLC, this routine adds 2? snd 2 and prints the 
ADC #$02 resulting byte, which is 4. In multiple-byte additions 
JSR PRAYTS C is cleared ai the start but subsequently used to 


carry through the overflows, if they exist. 


CLD 


Clear the decimal flag. O:=0 
INSTRUCTION 


$08 (216 &3301 1000) 


CYCLES 
2 
Flags: ry -8 O01 zc] 
9 


Operation: The decimal fiag is set 0; alt other flags are unchanged. 




























ADDRESSING 


4 : BYTES 
CLD implied e 


Uses: Resets the mode for ADC and SBC so that hexadecimal (binary) arithmetic 
is performed, not binary-coded decimal. Typically, SED precedes some 
decimal calculation, with CLD following when this is finished. 


Notes: Commodore BASIC uses no decimal mode calculations; on switching the 
machine on, CLD ig executed and the fiag is permanently left off. Entry 
to the monitor clears D, should it happen to have been set. There have 
been reports that future KASICs may contain BCD arithmetic, 


CLI 


Clear the Interrupt disable flag. 1:=90 




























INSTRUCTION ADDRESSING BYTES | C 
$58 (68 oid) sodd) [Cit Implied fe ‘maa 





Flags: {INV -BDIZC 
0 


Operation; The interrupt disable flug [s set to 0. From now on, interrupts will 
be processed by the system, using the IRQ vector In (SPFFE). 


Notes: {1} Interrupts through the NMI line (‘non-maskabl . 
PO uecieoe ne Lhe, muskable interrupts'} take place 


[2] Commodore use the Interrupt to proceas the keyboard and clockt. 
Typlenlly, CUI is used after SEC plus changes to intureupt yectors, Often 
CLE isn't needed when used with BASIC, #8 4 number of HASIC routines 
themsclyes use CLI, See SEU for an cxample including CLI . 


| BYTES | CYCLES 
o I . ae 


Clear the internal overflow flag. V:-90 


INSTRUCTION _ ADDRESSING 
$Be (194 41011 1690) 









CLV Implied ~~ 








ade tal iia 
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CMP 


Compare memory with the contents of the accumulator. PSR set by A- M 








INSTRUCTION ADDRESSING CYCLES 












CMP (zero page, 
CMP zera page 
CMP # immediate 
CMP absolute 

CMP (zero page).¥ 
CMP zero page,X 
CMP absolute, Y 
CMP absolute, % 





$C1 (193 81700 007) 
$C5 (197 $1102 0101} 
C9 (201 %1t00 1001} 
$CD (205 81100 1191) 
$Di (209 $1107 0091) 
$05 (213 $3301 0101) 
$D9 (217 $1101 100t) 
$OD (221 41107 1301) 


*Add 1 If page is crossed 















Ww hw NM w& RA Bd 








Flags: [NV -BOIZC 
x x x 


Operation: CMP affects three fiags only, leaving registers and date intact. The 


Uses: 


tHe Rave AL oon bie aathurdly, ot Gerry Weinberg that poor tual lty 


accumulator is not changed. The byte et the address specified by the 
opeode is subtracted from A, and the three flags N, Z,and C set depending 
on the result. Thus, if the accumulator holds the same value as the memory 
location, the result is zero, and BEQ causes the appropriate action to be 
taken. Before performing the subtraction, the carry bit is set by the chip. 
Within the chip, what happens is that the aecumutator's contents are added 
to the 2's compiement of the data. and the result of this determines how 
the flags are set. 


[1] With the zero flag. 2. This is the easiest flag to use with CMP*:- 
FF22 JSR FECF; INPUT A CHARACTER 
FF25 CWP #$20; 18 IT A SPACE? 
FP27 BEQ FF22; YES, INPUT AGAIN 
FF29 CMP #$0D; IS IT C.RETURN? 
PF2B BEQ FF47; YES. BRANCH ... 


FF2D CMP #$22; ..NO. MAYBE "? 


(2] With the cerry flag, C. This is quite straightforward. If the memory 
contents are less than A, or equal to A, the carry flag is set. ‘Less than’ 
means in the absolute sense, not the 2's complement sense, Thus, 100 is 
lesa than 199, although in 2's complement notation, 190, being negative, 
would count as the smailer number of the two. 





This is part of a routine 

to parse BASIC lines from 
the keyboard; the characters 
it looks for are typical of 
such routines. 





LDA 08sD This is part of CHRGET, where A is londed with one 
CMP #S3A byte of the BASIC program in memory. it’s then pro- 
BCB 0087 cessed; see Chapter [4 for detuils. This extract 


CMP #$2¢ compares with the ASCII for a colon, which is #3A, and 
‘ne branches for any less value, or if equal, to RTS. 

LoY #300 This example shows how a runge of valucs may be tested 
LDA {PTR),Y for und processed. Starting with the lowest ranges. 

CwP #$20 compurisons are curried out until the carrect runge is 
BCC Bl found: cach comparison ta followed by a branch to Bl, 
cup #340 B2 cte, where processing {x carried out for O- HIF, #$20- 
pec D2 #$39, und 50 on. 


bee 


12] With the negative Muy, N. Thin ia the must obscure Ang to use with 


CMP, ‘The reason ia that 2's complement ouadbers are nusunmiedd, and tf you 
are working with these GMP operules a4 mxpeeted, subtracting, thu: mastery 
from the aceumutstor, and therefore giving? a negative answer vehonever The 
memory excerda the nesumiletor. EF both oambers are positive, oF both neg: 
ulfve, dhe N Msgr ls seas though absolute subtractlon ware belng used, ana 
fn these clrcuetstances BMPEABPL enn te used. But if the two dati items have 
Uif ferent sites. Gee enaparisan: preset ix complicated by Lhe Fict that the ¥ 


Dit muy reyieler titernal averflow. See Chapter Lt for ger dietail. 


mach bra-rode 


tavariably haa a branch uf inte type, you have Geen warned! 
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CPX 


Compare memory with the contents of the X register. PSR set by x-M 





INSTRUCTION ADDRESSING 
SEO (224 BiTtd 0000) CPX F immediate 





SEQ (228 $1110 6700) CPX zero page 
SEC (236 $1110 1100) CPX absolute 


Flags: |INV-6BODiIZC 
x x x 


Operation; CPX affecty three flags only, leaving the registers and data intact. The 
byte referenced by the opcode is subtracted from X, and the flags N,Z,and 
C set depending on the result. Within the chip, X is added to the 2'a comp- 
lement of the data, and the result of this determines how the flags are set. 


Uses: [1] With the zero flag, Z. This flag tests equality. 


LOX #$00 
LOOP LDA $0270,1 . The loop in this example is part of the keyboard 
STA $026F,X buffer processing, showing how the contents of 
INX the buffer are shifted one character at a time. 
CPX $9E SSE is a zero-pege location, updated whenever a 
BNE LOOP new character is keyed in, which holds the current 
number of characters in the buffer: the comparison provides a test to end 
the loop. 
[2] With the carry flag. C. This flag tests for X>-M and X<M:- 
LDA $0G 
CPX #$50 The test routine is part of a graphics plot program; 
BCS EXIT; IF X»79 location $00 holds the horizontal coordinate, which 
he is to be in the range 0-79 to fit the screen. The 


comparison causes exit, without plotting. when X holds 80-255. 


[4] With the negative flag, N, When X and the data have the same sign, i.e. 
both are O-L27 or 128-255, BMI has the same effect as BCC, and vice versa. 
When the signs are opposite, the process is complicated by the possibility 
of overflow into bit 7. For example, 78 compared with 225 sets N=0, but 127 
compared with 255 sets N=1. (Because 225=-31 as a 2's complement number; 
thus 79+312109 with N=0, but 127+31=158 with N=!) 


CPY 


Compare memory with the contents of the Y register. PSR set by Y -M 


INSTRUCTION | ADDRESSING _ BYTES | CYCLES 
$CO {192 81160 0000) | CPY # immediate 34 ; 
$C4 (196 81100 01G0) CPY zera page 
$CC (204 %tiG0 3100) CPY absolute ogo 


Flags: [NV -BDIZC 
x . x x 


Operation: CPY affects three flags only, leaving the registers and data intact, The 
byte referenced by the opcode is subtracted (rom ¥, and the Muga N, Z, 
and C set depending on the result. Apart from the use of ¥ in place of X, 
with the resulting asyiometry in the implementalian of addreashig. inn 
opeada Is Identical in ite effects ta CPX. 






























Notes: Tho major difference in addreasing between X and ¥ is the fact that past- 
Indexing of Indirect uddressen ia ayalluble anly wilh ¥, So thin type of 


LOY #400 canalructlon, in which wo set of consecutive bytos, 
LOOP LDA (PTA),¥ perhaps a string in RAM or an error mesiage, in 

TAR QUTPLT proceased up io some knawt length, tends to umt 

Hig the Y register, 

CPY LENGTH 

BNE LOOP 


- 


eT rE RE ee TE EAT Tes CET ES em eT A PT PS 
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DEC 


Oecrement memory contents. M:=M-1 


ADDRESSING 
DEC zero page 
DEC absolute 
| DEC zero page, X 
DEC absotute, X 




















$CE (206 41100 1180) 
$D6 C215 ST1OF O1TG) 
SDE (222 $1101 1140) 
Flags: (NV -BOLZC 
x x 
Operation: The byte referenced by the addressing mode Is decremented by 1. 
getting the N flag and the Z flag. If the byte contained anything from 
#81 to #0, after DEC the N flag will be set; however, 2 will be O except 
for the one case where its value was #1 before the decrement, Probably 
#FF is added within the chip itself, setting N and Z on the result. Note 
that the carry bit is unchanged Irrespective of the outcome of DEC, 


Uses: [1] LDA $93 This short routine shows an efficient method to decrement 
BNE +2 a zero page pointer or any other double-byte yalue. lt uses 
DEC $94 the fact that the high byte must be decremented only if the 
vec $93 low byte is exactly zero. Compare INC. 


[2] Counters other than the X register and Y register can eusily be 
implemented with this command (or INC). Such counters must be in RAM; 
there is no ‘DEA' instruction. This simple delay loop which decrements 
locations $00 and $01 shows the type of thing:- 

AND #$00; FOR A CHANGE : 

STA $00 ; SET THESE BOTA A zero page decrement takes 5 clock cycles 


STA $01 ; TO ZERO to carry out; a successful branch takes 3. 
LOOP DEC $00 (We'll assume a page isn't crossed. as in 

BNE LOOP; 255 LOOPS... fact it is statistically untikely to be if this 

DEC $02 code is put into RAM at random). The 

BNE LOOP; ... BY 255 Inside toop therefore takes 9*255 cycles ta 


complete, and the whole loop ia a tittle more than 8*255*255 cycles. We can 
divide this by a million to get the actual tlme in seconds, which is about 
half @ second, 


DEX 


Decrement the contents of the X register, X:=X-1 
INSTRUCTION | _ADDRESSING __ BYTES | CYCLES 


“$CA (202 $1106 1010) | DEX implied ° 2 


Flags: (NV - BOEZES 
x x 


Oparation: The contents of the X register are decremented by t, setting the N 
flag if the result has bit 7 set, and setting the Z flag if the result is 0. 
Aa with DEC, the carry bit is unaltered. 


Uses: DEX (s almost exclusively used to count X in a toop, Ita maximuin range, 
of 255 bytes, Is often Insufficient, so several loops moy be necoasary, 
£12 UX #$1C 









$131 LDA EOrs,% This routine mavens 24 bytes from ROM to RAM, 

2194 STA GF,X including the CHRGET routine, In BASIC 2. 

£136 DEX 

R137 BNE F131 
LDx #$00 

LOOP LDA #$20 This is a Kerecn-clearing routing, which puts 1O00 
ATA $RKOUD, X bytes of #$20 Capace} Inte RAM. With an AG eolunm 
STA $8100," machitie onfy the tup half af the nereen blanks out, 
STA #49U0,E because $0 colummw by 25 rows gives 2000 Jocatlons, 
BTA $hJ00,2 
DEX 
BNr LOOP 
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DEY 


Decrement the contents of the Y register. Y:=Y-1 
INSTRUCTION ADDRESSING BYTES | CYCLES 
e 


JE imptied 2 


ae {136 41000 1000) | DEY imptied 


Pugs: (RV BOLE 


Cperation: The contents of the Y register are decremented by 1, setting the N 
flag if the resuit has bit 7 set (i.e. is greater than 127), and setting the Z 
flag if the result is #0. As with DEC, the carry bit is unaltered. 


12: 6502 opcodes 












Uses: DEY, like DEX, is almost exclusively used to count within loops. There are 
more opcodes which have indexing by X than by Y, so X ig more popular for 
this purpose. This example is Jess of a loop than those I've chosen for X:- 


LD¥ #$02 

LOA (PTA),¥; LOAD 2nD AYTe This inclusively ORs together three adjacent 
DEY bytes; so that if the result ig #0, each of 
ORA (PTR),Y; ORA 1ST BYTE the three must have been zeros. Note the 
DEY addressing mode, which is Lndirect indexed, 
ORA (PTR),Y; ORA OTH BYTE the indirect mode which ig post-indexed by 
BNE CONT ; END IF ZERO the Y register. 


EOR 


Accumulator's contents are exclusively ORed bitwise with the contents of memory. 
A:=A EOR M 


INSTRUCTION ADDRESSING 

1 ( 65 Bi00 DoOTI EOR (zero page, xX] 
69 $0100 101) EOR 2ero page 
73 $0100 1001) EOR # immediate 





77 $0100 1401} absolute 

81 €010) 0001} EOR (zero page],¥ 
85 20101 OT01} EOR zero page, X 
85 40101 100%) EOR absolute, ¥ 

93 30101 1101} EOR absolute, X 


*Add | if page is crossed 


Flags: |NV-BOIZC 
x x 


Operation: An exclusive OR {compare ORA for a description of an inclustve OR) 
is a logical operation in which dita are compared, and EOR is considered to 
be ‘true’ if A or B - but not both, or nelther - {is true, For example, 
let's evatuste FAB EOR #5F. Now #AB is 31019 1011, i.e. In decimal, ten 
followed by eleven, #5F is 40101 1111. So the EOR of these two is 
@1L1i 0100, or #F4, We orrive at this result by a process of bit comparisone, 
where bit 7 is # EOR 1=2, and so on, 


Uses: [1) CBM graphics use bit 7 to signi reverse video, In BASIC, this screen 
POKE can be used to reverse ony character(s): POXE P, (PEEX(P) OR 128} 
AND NOT (PEEK(P) AMD 228}. Thia excluslvely-ORs the high bit with the peck 
value, reversing the video byte. In machine cude, the samo reverse cffect 








LDA LOCN Ja more elegantly and quickly achieved with this 
EOR #9490 EOR, which is not directly availably in BASIC, 
BTA LOCN Chaptur @ has inore on thin topie. 


[2] ROR ja exceptionnl among CHM and 6502 logical funetlona in that no 
‘Information’ in the technical sense |x lost, If you repeatedly AND, you will 
finkah with #0, if you OKA, you'll end with #FP. For this reason, hashiotuln 
and data enecyption alyortthms often use EO. To code data, each byta Ix 
EORad with a byle gonerated by some secret, repentable process. When the 
result ta EONed agaln with tho identical sequence, all (he arlginal byte aro 
restored, 


- 


> cement FE Ee ee re RT ALY TTT TE Pitaeyt sniestaln hailed SO RR St RTT ESAS 
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INC 


Increment memory contents. M:=M+t 


INSTRUCTION —__ ADORESS!NG 
$E6 (230 #1110 G1l10) | INC zero page 
SEE (238 $1110 1110) INC absolute 
$F6 (266 Bi1tt O11) INC zero page,X 
SFE (254 $11tT 1110) | ENC absolute, X 


Flags: : V-BDizC) 


i i is i ted by 1, setting 
eration: The byte referenced by the addressing mode is incremen by ttin 
ee the N flag and the Z flag. The N flag will be i if the contents high bit is 
1, and otherwise 0; and Z will be 1 if the contents now equal zero exactly. 

The carry bit is unchanged. 
: , ct . =A 
1) iNc $93 This short routine shows an efficient method to increment 
ee BNE CONT zero page pointer or any other double-byte value, The high 
INC $94 byte must be incremented only when the low byte changes 
CONT ... from #FF to 460. Compare DEC. : 
i implement counters in 
21 Exactly as note {2} in DEC, {NC may be used to imp 
aM hers the X and Y registers are insufficient. Suppose we use the IRQ 
interrupt servicing to (say) flash a cursor or repeat u key. Something like: 
























CYCLES 






BYTES 
oa 











gen 
aoc 
ooo 






5 
6 
6 
7 






Uses: 


I INC $00 : ; 

is BEQ +3 where [RQCONT is the interrupt's usual routine enables 
JaP IRQCONT some periodic routine to be performed. Here, the zero 
LDA #20 page location $0 is used to count from #20 up to #7F and 


STA $00 #00, so the processing occtirs every 255-32=223 jiffies - 
a about every 3.7 seconds. 


Notes: [1] The accunmlator can't be incremented using this; CLO/ ADC #01 or SEC/ 
ADC #00 must be used, or TAX/ INX/ TXA or some other variation . 


i i ts are to be 
2) Remember that INC doesn't load; if the incremented conten 
be in A, or ina register, then INC $C6 say must be followed by LDA $C6 


or LDX $C6 or LDY $6. 


INX 


Increment the contents of the X register. X:=X +1 
INSTRUCTION ____s | ADDRESSING 
$€8 (232 $1110 1000) | INX implied 


Flags: (NV-BDI2 Ci 
x x 














. 2 


re Ineremented by 1, setting one N Ae 
i , These flags 
if the result has bit 7 set, and the Z flag if the result ia zero 

may both be 0, or one of them may be 1; it {s impossible for both to be sect 
l by this command. The carry bit is unchanged. 


Uses: INX |» common ag a loop variable. It ta also often used to set miscellancous 
values which happen to be near each other, Ilke thls: 
Lox #300 
STX $0334 
8TX $033C 
INX 
STX $10 
Btack polnter processing tenda to he connacted with the use of uy x 
roginter, becauxe TXS and TSX are the only wayn of accenalng SI aus 
of CAM‘s stack handling and memory checking for BASIC uses tho X register, 





Operation: The contents of the X register a 


AAA mm A m= RN I RT: OR TS CR et nee ee 





Programming the PET/C8M -336- 


INY 


Increment the contents of the Y register. Y:=¥ +t 





INSTRUCTION 


ADDRESSING | BYTES 
°o 





$C8 (200 1100 1006) INY imptied 


Flags: (NV-BDIZC 
x x 


Operation: The contents of the Y register are incremented by 1, setting N-1 if the 
result has bit 7=1, and vice versa, and setting 2=1 if the result is zero, and 
vice versa. A zero result ig obtained by incrementing #$FF. Note that the 
carry bit is unchanged. 


Uses: Like DEX, DEY, and [NX this command is often used to contro! loops; and 
like them it is often followed by a comparison (CPY) to check whether its 
exit value has been reached. See CPY for a typical example. 


JMP 


Jump to a new fecation anywhere in memory. PC:=M 
INSTRUCTION ADDRESSING 


Suc ( 76 $0100 1160 





ODRESS BYTES |CYCLES 
JMP absolute gee | 





-$6C (108 $01%0 1100) JMP {absalute} ee 


legs: [NV B O12 ¢] 


Operation: JMP is the 6502 equivalent of a GOTO, transferring control to some 
non-sequential part of the program. An absolute IMP, opcode $4C, causes 
the following byte to be transferred to the low byte of the program counter 
and the next-but-one to the high byte of the program counter, resulting in 
a jump. The indirect absolute jump is more elaborate, and takes tonger: 
PCL and PCH are fonded from the address following JMP and from the next 
address respectively. This is the only absolute indirect command available 
on the 6502, 


Uses: JMP, unlike JSR, keeps no record of its present position, and transfers 
contrel unconditionally to its new destination. The resulting code is not 


LDA PTRLO reloentable and in the case of ROM routines not 

LBY PTRHE usually portable between CBMs, ge Oranching may 
JMP AOD be preferable where possible-i.e. in short programs. 
CMP #g$2c.sC;', These extracts from programa demonstrate how JMP 
BEQ +3 Is used. The first loads two pointers to a work area 
dMP ERROR for calculations; a routine to add accumulator #! to 


Ses - this data iw jumped to. The second is part of a 
parsing subroutine which checks for a comma in a BASIC line; {f the comma 
has been omitted, an crror message ix printed to inform the user of this fact. 


Notes: [1] fndirect addressing. This ls a 3-byte command which thercfure looks like 
thin: IMP (30072) Sr ae ($7FFO). A conerete exumple is the IRQ veeter in 
the CBMs, When o hardware Interrupt occurs, an Indirect jump ta ($0790) 
takes place. (($012$)in BASIC 1). A look ot this region of RAM yilth the 
monitor reveals something like this: 

-! Q090 cE 24 17 FA AG C3 00 ¥F NOTE! THIS IS HASIC 2 
So IMP ($0090) f4 equivalent te JMP SEGZR. And JMU €$0092) jumps to $PD17. 
Palen of bytes ean be used in thin way to form an ineiireet jump table. Note 
that thia instruction has a bug: JMP (S02FP} takes Ith new address from 
S02FF and $0262, not S030. 


{2} ISK, RTS, and JME. Ap the depth of subroutine nesting grows with 
increasing progrnm compiedty, inevitably somy xubroutines whieh themselyvas 
call other sudretilines deviatap cove like this: 

LOAD VALUES And the polnt de that a subroutine call follawed by a 


JIR PROCKNS return In exaetly identlenl loa jump. accept that the 
JOR CHECK stack uae ba tesa ond the thatag ia abarter. Heplaelog 
RTS JAR CHECKY RTAby Jer CHECK in a common trick , 


ae? AF TT te sees A 
TE I ST MOE ENN ASTIN, PEM ITO LN EO I OP AN MNES SETS WAG Te MON I 
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JSR 


Jump to a new memory location saving the return address. 
§:=PC+2H, SP:=SP-t, S:2PC+2L, SP:=SP-1, PC:=M 


INSTRUCTION ADDRESSING 


$20 ( 32 $0010 0006} JSR absolute 








BYTES 


go0 













CYCLES 
6 


Operation: JSR is the 6542 equivalent of a GOSUB, transferring control to another 
part of the program until an RTS is met. which has an effect like RETURN. 
Like BRK, this instruction saves PC+2 on the stack, which is the last byte 
of the JSR command, RTS therefore has to increment the stored value in 
order to execute a correct return. Note that no flags are changed by 
JSR. RIS also leaves flags unaitered. 


Uses: {1] JSR is a very valuable commandand isused a great deal in complex 
programs: see for example the ROM BASIC interpreter. It has drawbacks 
which are similar to those of JMP. In particular, JSR is not relocatable 
except as regards fixed addresses such as those in ROW; and even these 
don't usually cacry over between ROMs. The exception is the so-called 
‘keenel' commands. ¢SR $EFES is a GET command and is relocatable in the 
usual sense between any CBM ROM. Nate that the 6809 has 'BSR', branch 
on subroutine, with both short and long offsets permitted. which overcomes 
the relocatability difficulties +. 


LOOP JSR FFE4 The first two examples here show how ROM routines 
BNE LOOP in the kernel may be used. It is not necessary te 
know how they operate; all that's needed is know- 
ledge of their principal features, which in these 
examples are that data is transferred by the accum- 
ulator, and that the flags are set by FFE4 as though 
LDA had been used. So the first example loops until 
a non-null byte has been fetched; the second loads 





Fiags: (NV -8DIZC) 


LDA CHAR 
J5R FFD2 


0300 BNE 0305 
(9302 JSR 0308 
0305 JMP LRQCONT 


0308 PROCESS a byte from memory and outputs it to cassette or 
We chee printer or whatever. The third example. part of a 
RTS routine inserter into the IRQ servicing routine. 


0300 JGR ZOP9; INCREMENT GETCHR ADDRESS 

0310 JSR CC9P; EVALUATE EXPRN; PUT IN ACC#1 
0313 JSR D72C; ADD .5 TO ACCH1 TO ROUND 

0316 JSR DGD2; CONVERT ACC#1 TO INTEGER IN ($11) 
O319 J3a@ CS2C; SEARCH YOR LINENUMDER IN BASIC 
O31C BCS 0321; CARRY S2Y IF FOUND 

O31Z UMP C7EB; 7ENDEF'D STATEMENT EAROR 


ace ae 


has checked for some condition - possibly # particular keypress - and, if 

the condition was true, calls a@ subroutine before returning to the interrupt 
aervicing as usual. This example Hlustrates the point made before about the 
problem of relacution. Suppose the routine were shifted to 4 new part of 
RAM, It would reappear as: 0200 BNE 0206/ 0202 JSR 030H/ 0205 ua? IRQCONT/ 
0208 PROCESS ... RTS. What ts wanted iy ISH 6208, Sce Chapter 14 on thls 
subject. 


The fourth example bs part of a computed GOTO routine for BASIC, which 
ties ROM routines Cin fret, BASIC 2 routines), BASIC subroutines provide 
debugyed code, but nend rewrltlag to cope with ench iiew furue of ROM, 


Notes: See RTS for the PLAS PLA vonateuction which ‘pops! ane subroutine return 
addross from Uhe slack. HTS also axplina the special constevetion In whick 
eo address Cnirua 10) ls puabed onto the stack, generating a Jump wher 
RTS oecura. Finolly, see IMP for a note an the way ta whieh Jal... /RTS 
may be replaced by IMP... 


Very often there lana need to worry stout thia aspect of the 8502, aft courses. 


em a EE, ORO PERE RA EN ATCA IIS ORNL, = REM AT eee RA I PEE, BAT A = 
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LDA 


Load the accumulator with a byte from memory. 


INSTRUCTION _|_ ADDRESSING 
SAT (is) S010 DOOT) | LDA [zero page,X) 
$A5 (165 41010 6101) LDA zero page 
SA9 (169 WOO 1001) LDA # immediate 
$AD (173 41030 1161} LOA absolute 

$81 (177 €1011 0001) LDA {zero page}, Y 
$85 (181 $1011 0103) LDA zero page,X 
$89 (385 $101T tO0f) LDA absolute, ¥ 
Sab (189 Bots 1101) LDA absolute, X 


*Add 1 if page boundary crossed 


Flags: |NV-BDIZC 
x x 

































































Operation: Loads the accumulator and sets the zero flag Z to 1 if the accumulator 
now holds zero (i.e. all bits = 0). Bit 7 is copied into the N (‘negative’) 
fag. No other flags are altered. 


{1} General transfer of data From one part of memory to anather needs & 
temporary intermediate store of data, which A (or X or Y) can be. As an 


Uses: 


EDX #00 example, this program transfers 256 consecutive 
LDA 7000,K bytes of data from S7000ff to $8000 ff. The 

STA 8000,% accumulator is alternately loaded with data and 
DEX written to memory.‘ 

BNE -9 


[2] Some binary operations use the accumulator: ADC, SBC, and CMP al! 
require A to be loaded before adding/ subtracting/ comparing. The addition 
or whatever can’t be made directly between two RAM locations. (Even if 
it cquld the opcode would make u 5-byte instruction). 

LDA 97 ; WHICH KEY? 

CuP #FF ; PERHAPS NONE? 

BNE KEY ; BRANCH IF EEY 


[3] LDA $2843 When the CBM is switched on, the code it executes 
contains this instruction. It initlalises a register 
by reading from it, The value is not important; the fact of reading out is. 


LDX 


Load the X register with a byte from memory, K:=M 


INSTRUCTION ADDRESSING 1 BYTES | CYCLES 
$AZ (162 $3010 0001} LDX # immediate o8 2 
$A8 (166 FOTO 0101) LDX zero page j 
SAE (#79 31619 1110) LOX absolute 

$86 (182 B1011 301) LOX zero page,Y 
SBE (190 b101t 11430) LOX absolute, ¥ 


*add 1 if page boundary crossed 


NV-BDIZC 
x x 
































Flags: 
Operation: Londs % from memory and sats 271 if X now holds zore, Bit ? from the 
memory ix nino capled into N, Ne other Mags are alteren, 


(1) Transfer of duta and holding Ceinporury values (e.g. fur comparivons ), 
Those closely resemble LOA (y eve} 


[2] X nas two characteristics which dlstingulsh ft from A; at ia in direct 
communication with the sluck pubtter ond it can be used ay an offant with 
Indexed addressing. Cloecer are other differeneen Igo!) So conatructlans 
Hike these wre canmon: LOR #8FR/ TRI and LOX $004. / TDEXS ANE .., 


Uses: 


*Home chips (e.g. 780} heve documentation in which "Joad' muane ‘land inte neenry’. 


- 


So Me Tre Tee IE rebar mt ee ye 
z ee ae rer ce ha, SO 2 FN SEI, I NN Se TREN TERIA Aan mein oman inane Pee 


Ee =e PI ON a ere i A eR RI ET 


-339- 
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LDY 


Load the Y register with a byts 


INSTRUCTION a 
$A0 (160 $1010 0000} 
SAR (164 %10T0 0100) 
SAC (172 31030 1100} 
$B4 (180 S101! 0100} LOY zero page,% 
SBC (186 B101t 1100) LDY absolute, X 


*Add 1 if page boundary crossed 


fram memory. Y:=M 


ADDRESSING __ 
COY # immediate 
LOY zero page 
LDY absolute 







































Flags: INV -BDIZC 
x x 

Operation: Loads ¥ from memory and sets Z=1 if Y now holds zero. Bit 7 from 
memory is copied into N. No other flags ace altered. 


(1) Transfer of data and storage of temporary values: Cp. LDX, LDY. 


[2} Since ¥ can be used as an index, and can be incremented/ decremented 
easily, it is often used in loons. However, X generally has more combinations 
of addressing modes in which it is used as an index; often therefure X is 
reserved for Indexing. while A and Y between them process other para- 
meters. When indirect addressing is used this preference between X and ¥ 
is reversed, since (usually) LDA {addr,X} is less useful than LDA (addr),¥. 
Lpy #00 X HOLDS LENGTH 
LOOP DEX DECREMENT IT 
HeQ EXIT , EXIT WHEN 0 
LDA (PTR},¥; LOAD ACCUMULATOR 
JSH PRINT ; PRINT SINGLE CHR 


Uses: 


rey 


This (admittedly rather unexciting) 
example shows how A,X, and ¥ have 
distinet roles; the ROM routine to print 
the character is assumed to return the 


cup #0D ; EXIT LF original X and Y values (as in fact it 
BEQ EXIT ; ‘KETURN' does). 
BNE LOOP ; CONTINUE LOOP 


Shift memory or accumulator right one bit. foyel7 6 54 321 o}e{C] 


INSTRUCTION _ ADDRESSING “BYTES | CYCLES 
$46 € 70 %OrOO 0110) LSR zero page bd 
SYA ( 74 $0100 1010) LSR accumulator | +. 
$x— ( 78 tOTGO 1710) |; LSR absolute 
$56 ( 86 40101 0110) | LSR zero page,X os 
$5E ( 94 80101 1410) LSR absolute, X 


Flags: [NV - BD 12.¢ 
0 x x 


Operation: Mover the contents of memory or the accumulator right by one bit position, 
putting 0 into bit 7 and the negative flug. and maving the rightmust bit, 

bit 0, inte the carry Mug. Z is set to 1 If the result is zero, and cleared 

if not. Z can therefore only become 1 if the location before LSK held vither 
#Oor FL. 

{1] This Ingtrueticn is similne to ASL Cand couls) just as well be colled 
‘arithinetie shift right). A byte ia kalved by this inatrugtion Cuileis la 
deelmal wade, with D sel}, its remainder moving inte tha carry (Mag, sce 

for sxampie the machine code corresponding to the BASIC TSET! command, 
which halves tie coordinates of a post in Sit peaoiuuon’ gruphics to fit 

the sereen. A rotate comand can save the carry bit; ave ROL, 

(2) Miseetlanesus Uses Inelude: (1) CSR! LS? LSA LSR move a high nybble 
Inte a tow nybbie, (iy LARS UCL Cesta bit 0, and beanchen If dt was noel set 
te 1; (Wd) LSH turns off bit 7, sometimes this ia ath caay wy lo wativert a 
negative number indo ste powttive equivalent, when the ain t4 stored aan 
aeparaie byte. The HASIC ABS functlon fue instange does Utia. 



















































Uses: 


2 NE EE RY ET eT AE FE 








Programming the PET /CBM - 340- #2; 6502 opcodes 


NOP 


No operation. 






















INSTRUCTION __ “ADDRESSING BYTES | CYCLES 
SEA (234 31110 1010} | NOP implied ° 2 





Flags: f* V-BOtEZ <| 


Operation: Does nothing. (Well, not quite nothing - it increments the program 
. counter and continues with the next opcode). 


Uses: [1] Filling disused portions of program, this is useful with hand ‘assembly’ 
and other methods where recalculation of branch addresses and so on can't 
be done easily. Some CBM ROM has this feature: for example, BASIC 2's 
PEEK has many NOPs left over from deleting the PEEK protection from 
BASIC t. 


[2] Conversely, when writing machine-code which husn't been thoroughly 
thought out beforehand (! am assured that this does very rarely happen) 

a large block of NOPs, or occasional sprinkling of them, can muke the task 
of editing the code and inserting corrections easier. There is some time 
lost in this process; NOP can be used as part of a timing loop. 


ORA 


Logical inclusive OR of memory with the accumulator. A:=A Inclusive OR M 
INSTRUCTION ADDRESSING _ CYCLES 


$01 ( t 20000 COOI) GORA (zero page. X)} 
§ 20000 0101} GORA zero page 

9 30000 1001} | ORA # immediate 
13 %0000 1101} | ORA absolute 


{ 
i 
$11 ( 17 $0001 0001) | ORA {zero page), ¥ 
{ 
( 
( 


















21 40001 0101) ORA zero page, X 
25 30001 1001) ORA absolute, ¥ 
29 $0001 ORA 












140%) absolute, X 


*Add 1 if e@ boundary crossed 
pag Y 


Flags: |NV-BOIZC 
x x 





Operation: Performs the Inclusive OR of the & dits currently in the accumulator 
with the 8 bits referenced by the opcode. The resuif is atored in A, If 
either bit is 1, the resulting bit is aet to 1, so that for example: 

BOOLL 0101 ORA WOCO 111) is 4001} 1111, The negatlve flag N, and the 
zero flag Z, are get or cleared depending on the result. 


Uses: [1) ‘Flagging in' a bit or bits. This la the oppesite process to ‘masking out* 
bits, as described under AND. These two examples are typical extracts 


LOA (PTR),Y from larger routines which use this function; the 
ORA #$HO first loads a character from the screen, then seta 
ORA $06 the high bit, reversing it - unless the character 
STA 396 wns already in reverse, ii which came Lt Is left 
unchenged, (Cp. KOR), The sucond i¢ the method 


by whlch au error code of #142. #4 or whatever, held In A, ls flagged inte 
the statun byte ST. ST fa stured in $94, Note the necarsity for STA $96, 
without it, only A holds the correct value of ST. 


[2] Other pilscellancoun uses ineiudy the testing of severol hytesa for cand- 
jtlonk whieh are intended to be true Cor eneh of them, for instyncen that 3 
conseeutive bytes are ail zero, or Ibat aeveral bytes all have bolt 7 equal to 
nero, LBY #00/ LDA CPTA),¥/ INV/ ORA (PTR),¥/ IN¥/ ORA (PTR), ¥/ BME... 
branchos If one or more byter contains m non-zero value, 


FR re nr te Tey a PRE LAUER SSPE FEE 7 AI I TN 
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Push the accumulator’s contents onto the stack, S;=A, SP:=SP-1 

Sua ( 72 $0100 1000} 
Operation; A is put into the stack at the current position pointed to by the stack 
pointer; the stack pointer is decremented, This diagram illustrates the 


INSTRUCTIGN ADDRESSING BYTES ‘CYCLES 
PHA imptied s [3 
rings: [NV BDIZC! 
position before and after the ‘push':- 


30100 --- MAXIMUM EXTENT OF THE STACK --- S01FF 
STACK _IN_USE 
SP (STACK POINTER) 


P (STACK POINTER) 


Uses: This instruction is used for temporary storage of bytes; examples inctude 
intermediate values of calculations produced during the parsing of numeric 
expressions, temporary store while A is processed for later recovery, storage 
when swapping bytes, and storage of A,X and Y registers at the start of a 
subroutine, to be recovered on exit. The example shows how a printout 


PHA routine works which is designed to end 
AND #7F ; WASK OFF BIT 7 when the high bit of a letter in the table 
JSR PRINT; OVTPUT 1 CHR is 1. The output requires the high bit 
PLA to be set te 0; but the original value is 


BPL LOOP ; CONTINUE IF AIT 7=0 recoverable fram the stack and may be 


used in a test for the terminator at the end of the message. 


PHA This next example shows how A.X and Y 
TXA can all be saved on the stack for future 
PHA recovery. Naturally these three registers 
TYA must be recovered in the reverse order: 
PHA PLA/ TAY/ PLA/ TAX/ PLA. 


Note: ‘Push’ is a rather misleading term for the action of this instruction, and the 
well-known ‘stack of plates’ analogy is also seriously misleading, and no 
doubt responsible for the puzzlement with which the stack is often viewed. 


PHP 


Push the processor status register’s contents onto the stack, S:=PSR, SP:=5P-1 
INSTRUCTION ; ADDRESSING 


oA VON, N BYTES | CYCLES 
§ to000 1000) | PHP implied ;é 


$08 ( 


Flags: pees 


Operation: The operation [9 exactly almilar to PHA, except that the processor status 
regisier is put in the stack, The PSR is unchanged by the push. 


Uses: Stores the entire aet of Mugs, usually eltther to be recovered later and 
d@laplayed by a monitor program, or for recovery followed by a bronch. 
PILP This feayos the slack In the condition (t waa found; 4 also 
PLA jonds A with the Mhag register, The Crest example under PUA 
shown the recovery of A, which sets elther/ neither of Nand ¥, The samy 
effect ein be achieved, with the full range of flags, with LOA CHAY PHP. 





TO marten tate ER NEL RT 9 SIRS Ch SR 9 A PI TS: ee ee 
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PLA 


Pull the stack Into the accumulator. SP:=SP+1, A:=S 


INSTRUCTION ADORESSING . 


$68 (104 $0110 1000} | PLA implied 


Flags: [NV -BDIZC | 
x x 


Operation: The stack pointer is incremented, then the RAM address to which it 
points is read and toaded into A, setting the N and 2 flags. The effect is 
gimilar to LDA. This diagram lustrates the position before and after the 
‘pull':- 

$0100 --- MAXIMUM EXTENT OF THE STACK -~~  $01FF 

















SP (STACK POINTEA) 


SP (STACK POINTER} 


Uses: [1] PLA is the converse of PHA. It retrieves values put on the stack by 
PHA, in the reverse order. So for example: 

PLA This code leaves the stack unchanged, but leaves 

PHA A holding the contents of the current ‘top’ of the 
stack. Flags N and Z are set as though by LDA. 
This next example shows how the processor status 
register may be examined by londing it into the 
accumulater from the stack. For example, if A now has bit 3 equal to 1, 
the decimal made is set. 


[2] A frequent use of PLA is to ‘throw away’ the top two bytes of the 
stack. This is equivalent to adding 2 to the stack pointer. This is done 

to ‘pop’ a return address from the stack; in this way, the next RTS which 
is encountered will not return to the previous JSR, but to the one before 
jt. It assumes, of course, that the stack has not been added to since the 
SR. The foliowing short example illustrates the point:- 


PHP 
PLA 


O33A LOK #FF Enter this trio of routines into a CBM with a monitor 
033¢ JSR 0340 (l.e, not BASIC i, unless a monitor is specially 
O33" BRE loaded}. However, use $0350 RTS at first, If the 


routine ig run, by .G 033A which goca to the 
machine-code address $033A and executes the code 
there, on BRK the registers are displayed, among 


0340 JSR 0350 
0343 LOX #01 


sisal etl them X, which equals #01, This is ordinary nested 
0350 PLA subroutine logic; the earlicr value of X is over- 
O3SL PLA written in the subroutine starting at £0340. But 
0362 ATS if you use routine $0350 as it appears here, the X 


register holds #FF on BRK. The return #ddreas of $0342, as it ix held in the 
stack, has been lost, so RTS goes siruight to BRK. 


PLP 


Pull the stack into the processor status register. SP:=SP+1, PSR:=5 


INSTRUCTION  ==-——s| ADORESSING __! BYTES | CYCLES 
$28 { 40 to010 3000) ! PLP implied |e 4 
ee Sr 


Flags: [NV-BDIZC 
aX” KM MK 


A ~ 
























Operation: The operation in exactly altar to PLA, except that the processor miatus 
reglater, not the accumulator, I loeder) from the stack. 


Uses: Recovers previously atered Maga wlitt which lo lest or breneh. Sve tha 
notes on PHP. This can alao be uaed to experiment wlth the flues, perhaps 
trylng te wet bit 4 Cwhleh is met to 1} of to wet ¥, for example. 


PL OPES Me ee en Sane FREE ATTY Te RR LT PETS Te ATH PNG Te BARN NER OE FORTIER C= gett 


Seren carmen 
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ROL 


Rotate memory or accumutator and the cerry ficg left one bit. 
Ger 654321 0} 





INSTRUCTION ADDRESSING 
40010 0110) ROL zero page 
#o0To 1010) ROL accumulator 





$O0TD 3110) ROL absolute 
yoot) 0110) ROL zero page,X 
$0017 1110) ROL absclute, X 





Flags: [NV -BDEZC] 
x x x 


Operation: 9 bits, consisting of the contents of memory referenced by the instruction, 
and the carry bit, are 'rotated' as the diagram shows. In the process, C is 
changed to whet was bit 7, bit 0 becomes the previous C, and the negative 
flag. bit 7, becomes the previous bit G, In addition, Z is set or cleared 
depending on the new memory contents. ‘ 


Uses: [1] Like ASL, ROL doubles the contents of the byte which it references, but 
in addition the carry bit may be used to propagate the overflaw from such a 
doubling. Mufuplication and division routines take advuntage of this property 
where a chain of consecutive bytes has to be moved one bit leftward. ROR is 
used where the direction of movement is rightward, and often these commands 
&re used together. 


i. ASL $4000 The first exampte moves the entire 24 bits of $4000 - 
ROL $4001 $4002 over by 1 bit, introducing 0 into the rightmost 
ROL $4002 bit; if there is a carry, the carry flag will be 1. 


The second example demonstrates an alternative 
ce method for clearing bit 7 of a location to the mare 

ROR $7F£3,2 obvious LDA / AND &7F/ STA. It is however far 

s ‘slower’, taking half as long again to execute. All 

rotations and shifts are slow, with the exception of operations on A which are 
as fast as the 6502 allows. [f possible, therefore, rotations and shifts should 
use A. Parity bits are a goad example of the type of application for which 
ROL is ideal. Zak's 6502 book has an example in which ONECNT holds the 
count of 1s in a byte, and A holds the character; what should follow is: 

ROL A ; BIT 7 OF THE CHR ANT YET RNOWN 

LSR ONECNT: PUTS 0 (SVEN), 1 (ODD} INTO C 

ROR A ; INCORPORATE C INTO BIT 7 


[2] Like ASL, ROL may be used before testing N,Z, or C, especially N. 
ROL A ; ROTATE 1 BIT LEFTWAAD 
BMS BRANCH; BRANCHES If AIT 6 WAS ON 


ti. KOL $7FE3,Kk 


ROR 


Rotate memory or pccusiutetor und the carry flag right one bit. 
E 1 o}*N@: ald 6502s lack this instruction, but al! PET /CBMs have it. 





INSTRUCTION ADDRESSING 
$66 (102 45170 0110} ROR wre page 
$6A (106 10316 1019) ROR accumulator 


SOE (110 Ort i110) | ROR absolute 
$76 (116 401TT 0110) ; ROR zero page,X 
S7E (126 2OLTE 3110) | ROK absolute, X 





Flags: [NV-ADIZ Cl 
[* x x| 
Cperation: 9 hits, conalstlng of the contents of memory referenced by Ure Ind ruction, 
and the carry bit, are ‘roteled' ng the dlngsam shows. Co becowes whith ws 
bH OD, bE T becomes ihe previous C, and % Ie act or cleared depending on 
ihe bytes current coments, For applleationa, nea ROL, 


SA = ke URE US a TR PEN RT CR RY INI ISS cee RRR ITT tS AURA AY Svs = Sone = 
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RTI 


Return from interrupt. SP::SP+1, PSR=5, SP:=SP+t, PCLi=S, SP:=SP +1, PCH:=5 











INSTRUCTION ____ | AODRESSING BYTES | CYCLES 
$40 { 6% $0700 0000 RTi implied 3 

Flags: |NV-8SO1ZC 
x x KX XXKRXK 


Operation: RTI takes J bytes from the stack, deposited there when the hardware 
triggered the interrupt, assuming that the stack has been tidied up before 
RTI with equal numbers of pulls following the pushes, The processor status 
flags are recovered es they were when the interrupt occurred, and the 
program cuunter is restored so that the program resumes operation at the 
byte at which it was interrupted. Note that A,X, and Y¥ are not saved or 
recovered automatically in this way, but must be saved by the interrupt 
processing and restored immediately vefore RTI. If you follow the vector 
stored in CBM ROM at (SFFFE), you will see this operation taking place. 


{1] Obviously, to resume after an interrupt. Unless you are using your own 


hardware to generate interrupts, or programming the VIA to generate inter- 
rupts, this instruction is unlikely to be useful to you. 


{2] However, it is possible, as with RTS, to exploit the automatic nature of 
this command to execute a jump by pushing 3 bytes on the stack, imitating 
an interrupt, then using RTI to pop the addresses and processor status. 


Uses: 


LDA EI 

PHA This routine, by simulating the stack contents 
LDA 10 left by an interrupt, jumps to 256*HI + LO (in 
PHA decimal!) with its processor flags equal to what- 
LOA PSR ever was pushed on the stack as 'PSR'. 

PHA 

RTE 


RTS 


Return from subroutine. 
INSTRUCTION 


rags: [RV 8 BIZ! 


Operation: RTS takes 2 bytes from the. stack, Increments the result, and jumps to the 
addreas found hy putting it Into the program counter. [t is simfiar to RTI, 
but does not change the processor fluga, since un important feature of 
subroutines is that, an return, flegs should de usabie, Aloo, unlike KT] in 
whieh the address saved Ja the address to return to, RTS must Increment 
the address it fetches from the stack, which points to the second byte atter 
a ‘JSR, (Presumably, the chip.usea the routine for BRK and for JSR in 
common), 


SP:=SP +1, PCL:=S, SP:=SP+1, PCH:=S, PC:=PC +1 


ADDRESSING | BYTES | CYCLES 
id 6 








JSR implied 








Uses: (1) To relurn after 8 subroutine. This is entirely stralgh forward : - 
O35A JBR 0280, CALL StMROUITING 
0330 RTS > RETUHK TO BASIC SYS 826 calls the routine at 
0250 STA $4000; PUT A IN SCREZK ei eee wee tea 
0353 RTS : RETURN calling a suibrontiog befere 
aa returning to asic, Fhe 
subroutine starts at 0450 and continues until RTS is Sound; this example amply 
pokes A intu the top left corner of the sereen bufore returnlag. 
Notes: [1] See PLA for the techoique for disenreing sabroutines! retara add roesnon, 


Also neo UMP fer te easontial lidentity of JSR .../ KES ane IMP... 
Flaslly, as with REE, 9 jump can be yeneralad by pushing bytes ante (he stack 
and oxewuting RTS, even though ne mibrautine cali was neluatly mace. 


SO I TE ES I a ag a Sewer: o nema est reas: mete 
A IN San Tg ne EP EE AOD AE ag mn Se RE TEND AS = 


oT ypemgeresnes? 7. 
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Programming the PET /CBM 


SBC 


Subtract memory with borrow from accumutator. 


INSTRUCTION | ADDRESSING 
SET (225 81310 0001) | SBC (zero page, X) 
$E5 (229 Ri110 0101) SBC zera page 
$E9 (233 $1179 1001) SBC # immediate 
SED (237 $1310 1101) SBC absolute 

SFY (291 $1219 0001) | SBC (zero page).¥ 


A:=A-M-{1-C) 


















$F5 (245 &111T 0101) | SBC zero page,X 
$F9 (249 BITE 1001) SBC absolute, ¥ 
$FD (253 $11 1107} sac 


*Add 1 if page boundary crossed 


Flags:|NV-BOTfZC 
. |x x x x 


Operation: it is ysual to set the carry bit before this operation, or precede it by an 
operation which is known to leave the carry bit set. Then SRC appears to 
subtract the data referenced by the addreasing mode from the accumulator. 
If the carry flag is still set, this indicates that the result did not ‘borraw’, 
ive, that the accumulatar's contents were greater than or equal to the data. 
When C is clear, the data exceeded the accumulator's contents and C shows 
that a ‘borrow' is needed, Within the chip, A is added to the 2's complement 
of the data and to the complement of C.*This affects the N,V,Z, and C flags. 










ona 
| 00 












absolute, X 





Uses: [1] Single byte subtraction. This has quite a number of applications: 
SEC ; CARRY FLAG {N KNOWN STATE The first is a conversion 
LDA CHR; ASCIE NUMERAL ('0'=#30 &C) routine whieh simply subtracts 
SBC #2%; CONVERT TO BYTE 00 TO 09 a fixed amount from an ASC3L 
JSR OUT; PRINT OR CALCULATE WITH VALUE numeral to convert it into a 
byte value 0-9, perhaps for the purposes of exlculation, Numerals have 
ASCII value 430- #29 (48-57 decimal) which subtraction converts to #0- #9. 
LDA HORIZ; LOAD CURRENT CORSOR POSN The next exeniple is more elab- 
SEC ; CARRY PFLAG SET DUAING LOOP orate and is a detail from PRINT. 
LOOP BBC MOA =; SUBTAACT 10S UNTIL CARRY.. When processing the comma in 
é BCS LOOP ; ..1S CLEAR (L.E, A IS NEG) a print statement, the cursor 
EOR #FF ; FLIP BITS AND ADD 1 TO is moved to position 0, 10,20, 
ADC #01 ; CONVERT TO POSITIVE, etc. Suppose the cursor is 
now st 17 horizontally; we subtract 106 until the carry flog is clear, when A 
will hold ~3. The 2's complement is 3, and 2 spaces or cursor rights take us 
to the correct pusition on the screen, Note that ADC #01 adds t only; the 
carry flag is known to be zero by that stage. 
[2} Double byte subtraction. The point about subtracting one 16-bit number 
from another Ge ihat the borrow is performed automatically by SBC. First 
C Is eet to 1; then the low byte is subtracted; then the high byte is sub- 
tracted, with borrow if the low bytes were such ug to make this nucnssury. 
SEC In this example #026A {a subtracted fran the 
LDA LO contents of addresaes (or data) LO and HI. The 
SEC 6A resntl Is replaced In LO and Ul, Note that SEC Is 
STA LO perlarmed once oly. In this way. borruwing ja 
LOA HT performed properly, For example: suppose Une 
BUC #02 address from which @26A in to be subtracted holds 
TA H! #1254. Wien tA is subtracted Crom #34, Che carry 
flag is cleared, ao thal #2 and 1 is subtracted from the high oyle #12, 
Subtreetion ja sometimes ave twee, ina way which clears the earry bit 
Tor vidoes in A within a eortuin range, Ui thin way, JSA.../8CC 2. may be 
Gaed, Sew Chaplas 1409 CHRGEU for an ecuaple. Other examples invtude 
oo check for alphatetle charictees CA ZA) only. 
Note: “derietly speaking, L'a complement and C are added to A. For sanapia: aEC/ 


LOA MAUS BBC POS takea BAO and adda AA and bide wilh Cet. Wherean FEU / 
LDA BAO/ SIMD AC taken #AN anc adda 4) and ]9#54 with ca). 


ey . 


. 
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1EC 
et the carry flag te 1. C:=1 


INSTRUCTION ADDRESSING BYTES | CYCLES 
r) Ty? 








$38 ( 66 36037 1000) [| SEC imptied 


lags: | N setae 
1 


peration: Sets the carry flag; this is the opposite of CLC, which clears it. 


ses: Used whenever the carry flag has to be put into a known state; usually 
SEC is performed before subtraction (SBC) and CLC before addition (ADC} 
since the numeric values the used ure the same as in ordinary arithmetic. 
See ADC and SBC for examples. 


1ED 


et the decimal mode flag to 1. O:=1 
INSTRUCTION | ADDRESSING _ ) BYTES > CYCLES 
. 2 





Sfe (249 21111 1006) [ SED implied ~ 


lags: (NV -BDIZC! 
See ae 
peration: Sets the decimal flag; this is the opposite of CLD, which clears it. 


ses‘ Sets the mode to BCD arithmetic ("binary coded decimal’) in whieh each 
nybbdle holds a decimal numeral. For example, ten is held ag #10 and ninety 
as #90, Two thousand four hundred and fifteen is #2414 in 2 bytes. ADC 
and SBC ure designed to operate in this mode as well as in binary, but 
the flaga no longer have the same meaning, except ©. 


Where indefinite precision iy required with caiculations buffers cun be 
allocated for storage and addition of large numbers. No precision will be 
lost within the range specified. (It's possidle to do @ similar processing fob 
on numeruls stored in single bytes; these of course occupy twice as much 
space, and take longer to work with). This mode is unused in BAS{Cs 1-4, 


EI 
et the interrupt disable flag to 1. 1:=1 
INSTRUCTION | ADBRESSING 1 BYTES | CYCLES 








$78 (120 80111 1090) | SEi implied “Te 


Jags: INV - BOL Z Cc] 
a sae 








peration: Sets the interrupt disable flag; this ls the opposite of Ci.1, which cleare It. 


ses: When this Mag has been set, na interrupts are procesked by thu chip, except 
non-maskable interrupts (which huve higher oriority) und resut. With CAM 
equipment, ordinary maskable hardware interrupta occur every 1/50th or 1/80th 
of a second; setting 1] will cauag (he processing sxpocluted with this, Loe. 
clock (Ti and T1%), keyboard and cessnttes, to ceaxe undid CLI, Maskesble 
interrupts are preenaacd by (SFPFE}, the BRK, [Ff the vector in the veey top 
locations of the BASIC ROM ts followed, Lhe interrupt servicing routines can 


023A Er be found. These are not Centicely) hardwired In 
0358 LDA #43 ROM: the veclora use an address in RAM before 
0330 BTA 20 jumping buck ta KOM, So the exatnplir Qure te o 
0J3¥ LDA #n3 lypleul Intiialiselion roullng ta redirect the vector 
034i STA 91 into the user's own progsam, where i may sel a 
0343 CLI mustead tone, Proves A repeat key, turn off STOP, 
0344 Rts or whalever, Sen Chapter £4 for mare detail, 


NR OE LIE TE ELT SP LE eT Te A EAE AY Rein Mt tae eRe pram ras 2 amen i | 


. 
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STA 


Stora the contents of the accumulator into memory. M:=A 


INSTRUCTION i ADDRESSING 
$81 (129 31606 9001} STA (zero page, X} 
$35 (133 $1000 0101) | STA zero page | 
$8D (141 #1000 1101) | STA absolute p00 
$91 (145 $1001 0001) STA (zero page),¥ 

$95 (149 $1001 010%) STA zero page,X 
$99 (153 31001 1001) | STA absolute, ¥ 
$90 {157 31901 STA absolute, X 





































Flags: [NV-BDIzc 


Operation: The contents of A are sent to the address referenced by the opcode. 
. All registers and flags are unchanged. 


Uses: [1] Transfer of blocks of data from one part of memory to another needs 4 
temporary intermediate store; this can be A,X, or ¥. This is alternately 
loaded and stored, See LDA. Another example in addition to the one given 

LOY #00 there is this outline of a 
LOOP JSR LOADCHA; LOAD A W1TH CHR routine, where LDA is carried 
STA (PTR),¥; STORE A INTO MEN out by some routine and 


w INC PTR ; INCREMENT POINTER there is a further routine to 
BNE TEST , gheck whether all characters 
INC PTR+L have yet been moved. 
TEST JSR TESTPTR; TEST FOR LIMIT 
BNE LOOP ; CONTINUE IF NOT EXD 


(2] Binary operations using the accumulator, netably ADC and SBC, are 
performed within the accumulator; 0 common bug in machine code programs 
is the omission to save the result; 

LOA $96; ST BYTE 

AND #$FD;BIT 1 OFP 

STA $96 ;REMEMBER THIS! 


[3}] Another very common use is storing {solated values during initialisation, 
. to set the contents of certain locations to known values: 


LpA #89 
STA 94 ; SETS ($94) 
LDA #C3 
STA 95 ; TO $C289. 
LDA #17 


ese ; ee, 


STX 


Store the contents of the X register Intomemory, M:=X 


‘INSTRUCTION  —_ | ADDRESSING. 
$a6 (134 $7000 0110) STX zero page 
$BE (142 31000 1110) | STX absolute 
$96 {150 $001 010) STX zero page, ¥ 











Flags: eee 


Operation: The contents of X ara nant to the eddrers referenced by the opcodn, 
Alt reginters and Qags ara unchanged. 


Uses: The usen are identical to those of STA; thers Is a tandency for X to be 
uned as an index, 40 STX la tesa usad than STA. 


ne me mpg ST ea me me canta a Meant Ne RR AT Ee 
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TY 


tore the contents of the Y register into memory. M:=¥ 


INSTRUCTION T ADDRESSING 














$84 (132 °$1000 0100) ; STY zero page 
$ac (940 G00 1100} 
$94 (343 $1001 0100} 


lags: [x v_- pec! 


Ne 2 = tn 









STY absolute 
STY zero page,X { eo 





peration: The contents of Y are sent to the address referenced by the opcode. 
All registers and flags are unchanged. 
























ses: STY resembles STX; the comments under STX apply. 
ransfer the contents of the accumulator into the X register. Xi=A 
INSTRUCTION ADDRESSING BYTES | CYCLES 
$AA (370 41010 1010} TAX implied 5 2 
lags: [NV -BDIZC 
x _ x 
LDX had taken piace. 
lses: This transfer is mostly used to set X for use as an index or a parameter, 


iperation: The byte in A is transferred to X. The N and Z flags are set as though 
or to temporarily hold A. These examples illustrate the type of thing. The 


THA first is from a ‘high resolution’ screen plotting 
BOR #FY routine; the odject is to pilot a bluck dot in a 

ORA a4 location with a coded value of 1,2,4 or @ in $94. 
EGR #YF X on entry holds the position of the current 

TAX graphics character in a table. On exit X holds the 
LDA TABLE,E position of the new character. Intermediate calcul- 


ations use the accumulator because there is no 


tk ‘EOR with X‘ instruction. The second example is 
PLA @ straightfurward reconstruction af X and Y values 
TAY stored on the stack. This has to be done when 


returning from interrupt processing. 
Inte: Registers A,X, Y and the stack pointer are interchangeable with one 
instruction in some cases, but not others, The connections ure these: 
YmASXSS. 


TAY ° 


‘ransfer the contents of the accumulator Inta the Y register. Y:-A 
INSTRUCTION ADDRESSING BYTES | CYCLES 
a 


$A8 (168 31030 1000) | TAY implied Bove 


NV-BDIZC 
x 


Iperation; The byte in A is tennsfurred to ¥. The N and 2 flagn are set us though 
LDY hind taken place. 


Jses; See TAX; TAY fs aslnilar to this other instruction. 




















‘Taga: 
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TSX 


Transfer the stack pointer in 


to the X register. X:=SP 
INSTRUCTION 
$BA (186 31011 1010) 


ADDRESSING. BYTES 
% 
Flags: (NV - BOUZC 
x x 


TSX imptied 
Operation: The stack pointer is transferred to X, Note that the stack pointer is 
atways used in conjunction with $0100, that is, when the stack is accessed 
the high byte of RAM is always get to #l. The pointer itself is a single 
byte. 
[1] To inspect the stack, in the case of CBM BASIC, for GOsuUB and FOR 
tokens when processing NEXT and RETURN. The stack pointer is also used 
. to estimate the amount of space left on the stack; again, CBM BASIC does 
this. typically printing ?OUT OF MEMORY ERROR if the stack is not 
sufficient for some manoeuvre. Since the pointer does not point at the last 
jtein pushed on the stack, but the byte below it, LDA $0101.% can be used 
to peck the last pushed item. 
[2j This is sometimes used to store the stack pointer when a different (i.e. 
lower) part of the stack is temporarity moved to for processing. 


TXA 
Transfer the contents of the X re 


INSTRUCTION ADDRESSING 
$8A (138 %1000 1030) | TXA implied 


—— rt 
Flags: [NV -8 DIZC 
* ~ x 
Operation : The byte in X is transferred to A. The N flag and @ flag are set as 


though LDA had taken place. 
Uses: - See TAX. 

























Uses: 






ister into the accumulator. A:2X% 
BYTES | CYCLES 
2 Z 
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TXS 


Transfer the X r 


Ister into the stack pointer, SP:=X 
INSTRUCTION ADDRESSING BYTES | CYCLES 
a aaa 5 > ares 


$9A (154 ¥3003 1010) 


Fiags: fe eetze| 


Operation: X is stored in the stack pointer. Now, PHA or PHP will place a byte 
inta the atack at $0100 + the new stack pointer, and PLA or PLP will pull 
from the next byte up from this. Also RTI and RTS will return to addresses 
determined by the atack contents at the new position of the stack. 


Uses: {1} TXS initiaiises the stack on switchon, when the RESET line is activated, 
and also in some BASIC commands liky RUN and CLR. The stack extends 
from $0100 - $OIFE in principle: this is the area of RAM which is reached 
as the stack pvinter varies from #0 to #FF. Not all of this is used by PET/ 
CBM machines. Since the stack pointer is decremented when data is pushed 
on to the stack - i.e. if memory is pictured starting at location zero on the 
left and increasing vightward, the stack 'grows' to the left az data is push- 
ed - the initial value is usually something like #FF on setting the machine's 
starting values: 


12; 6502 opcodes 















LOX #FF 
TXS 

{2] The other use is to switch to a new stack location. As a simple example, 
cic the routine presented here is an equivalent to 
TSX PLA/ PLA which we've seen under RTS to be a 
TXA ‘pop' command, deleting a subroutine's return 
ADC #02 address. Incrementing the stack pointer by 2 hag 
TAL the identical effect. For a more complex example, 
TKS see 'POP' in the BASIC reference section, which 


is simitar in conception but more complex in execution because of the 
greater eloboration of BASIC compared to machine-code. 


TYA 


Transfer the cantents of the Y register into the accumulator. A:=¥ 


INSTRUCTION ADDRESSING BYTES | CYCLES 
* 2 


$98 (152 B100T 1000) TYA implied 

























Operation: The byte in ¥ is transferred to A, Tho N Mag and 2 flag are set as 
though LDA had taken place. 


Uses: See TAX. The transfera TAX, TAY, TXA, and TYA ail perform elmilar 
functions. 


aad 
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13: Using ROM routines 


a 
CHAPTER 13: ROM ROUTINES AND THEIR USES 


A 


13.1 The RESET sequence. 

As we saw in Chapter 1!, the RESET line* in any 6502 is used to cause a jump to 4 
standard address (FFFC}. Most 6502-based equipment has a ROM routine which ig jump- 
ed to on RESET; thisinctudes CBM printer and disk systems. Disassembly of such 
routines can give useful information about # system. The input/ output chips’ RAM 
locations and contents on reset. for example, show which registers are configured for 
input and which for output, which interrupts are enabled. and so on. BASICa 1 to 4 
have similar reset routines, at FD38, FCD1, and FDIG in order, Chapter 15 lists the 
operations they perform. The routines are in two parts, like this: 

(i) On RESET, or on JMP (FFFC), the routine at FD38, FCD1, or FD16 is run. 

(ii) Most of the hardware-oriented aspects of the PET/CBM are initialised: the 
1/0 chips are configured to match the system, the screen is cleared (to erase 
its ‘random' garbage), the screen table set up in 40-column machines, the 
decimal flag cleared, and NM!f, !RQ and other addresses set up. 

(iti) Now the ‘diagnostic sense pin’ is checked; see Chapter 8 on ‘Reset switches’ 
for information about this. 

{iv} Depending on the diagnostic sense pin, BASIC is initialised (this is usual) - 
or MLM is entered, or, in BASIC 1, @ diagnostic routine may be run, 

(v) BASIC initialisation (at E0D2/ E116/ D385) sets the stack, USR address, 
CHRGET and the random number seed, BASIC start and end addresses, and 
other specific BASIC items. Finally, a loop tests RAM by writing #55 and #AA. 
into RAM from $04U0, until either $5900 is reached or the read-back value no 
longer equaly the poked value. indicating end of RAM. This leaves the end- 
of-memory pointer set; by subtraction, the number of bytes free is computed 
and printed. So a 32K system prints 31743 bytes, since 1024 + 31743 = 47FFF. 
(If a RAM chip is corefully removed, you may get (say) 15359 bytes free, 
where 1024 + 15359 = #3FFF>. 

Any of these routines can be entered, bypassing the eartier initialisation. Chapter 5 
has examples in SYS to clear the entire memory fram $00, aot just $0400. Nocmally 
the RAM below BASIC in untouched by RESET, which is why machine-code in the cass~ 
ette buffers can sometimes survive 4 power-off and immediate power-on. 


13,2) The interrupt routine. 

The CBM interrupt-processing sequence has two branches, like KESET. One is for BRK 
commands, the other for interrupts generated by the screen, and used to control the 
keyboard, tape, and cursor, These branches are distinguished by the presence or 
absence of the B flag in the status register; both BRK and IRQ share the sume vector, 
(FPFE). Disassembly reveala that A,X, and ¥ are saved on the stack (an intecrupt 
saves the program counter and status reyister, but not the other registers). and an 
indirect jump is mada to (90) for 1RQ and (92) for BRE. Kither of these addresses may 
be poked to point at user-written routines; Chupter 8 has several examples, involving 
repent keys, keyboard redefinition, and ya on; Chapter 9 also includes examples. The 
ROM in BASIC L uses ($0219) and ($021B) for [RQ and BRK, 


Example: displaying 6 part of memory continually on the screen The fairly short mach - 
ine-code routine presented here works like thls: 

BYS 834 awaltx input. 160 000A displays 10 characters from $9100 anwnrda; 

0200 OG28 dinplays 40 characters from the input bulfer, 

ft) uses MLM routines to input s poie of hex addresses, the first ef whieh is stored: in 
(FD), the necund in (FB). Some operitions will overwrite Unese addressed; thi can be 
avoided by using fsay) $00 ~ $02, at the est of a slightly longer progrum, The IRQ 
In diverted to run part of thia routine, beginning Ag 60 ..., whieh continually, tae, 
evary Sith or bfth of e second rewrfles ita date aft the top of the screen. Tn Ube way, 
numbers can be watehed helag formatted; the fapur buffer enn be watched, and so on, 
A maximum of 2o8 bytes ean te displayed > agilt, there It no resson why more can't 
be weed. Mute that SYS 6]4 then BOOL OOFF conbinually anlfta the Lop of tha acreen, 

SYS O71) turna Chea roution uff. . ; 
*Heforence to BGU2 data akeets aliowa Lilie procene le an folliws the Pine ta te be 
held lus un awitihon; 11 suet de held tow uathi lhe voltage Vee raachea ita operating 
(evel, and a Little longer; when RESET now goes high, the chip reseta Staolf in alex 
eyriaa, gota the thferrupt disable Clag, and [oada the program counter from CF FROT, 


ee cee yeatiig ane VMN MU Ene = Ge ALAIN pT Camere Mitete cokereee 1 6 carer SmmeTun, cae PGARENE LW © Wa-eROIPER EERO Ee Sar RIN enh I mm rr 
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ISPLAY BYTES USING IRQ: BASIC 2 VEASION BASIC 4 VERSION 


+3) G2TA 20 AT EF 20 G7 ET 20 BB O27A 20 54 D7? 20 44 D7 20 98 
> 0282 ET 20 A7 ET 78 AS O2 85 O282 DT 20 54 DT 738 AD O2 8S 

028A 91 AS $0 85 90 6a An’ OO O2sA 91 AD 90 85 90 GO AD OO 
.1 @292 AL FD 99 00 80 Ca .C4 FB 0292 Bl Fr 99 00 80 C& C4 Fa 
-: O29A DO Fé 4C 2E €6 78 AS EG O29A 00 FS 4C 35 E4 7H AD ES 
> @2A2 85 91 AG 2E 85 9O 60 xx Q2A2 BS 91 A9 55 BS 90 BO xx 


xample; pause loop By combining 
revirected interrupt with a ROM 


outine to GET a character from the O27A JSR FFE4 ;GET CHA. FROM KEYBOARD IN A 
eybourd, we can write a pause G27D CMP #40 8 6;1S IT @? 

op. This example is activated by O27F BNE 0288 ;NQO - CONTINUE [INTERRUPT 

?, a key for which there is usually 0281 JSR PFE4 ;GET ANOTHER CHARACTER IN A 
ttle use. The interrupt routine at 0284 CMP #40 


45 point enters a loop, in which it 0288 ANE 0261 -;KEEP LOOPING UNTIL @ 

ill remain until '@' is pressed again. 0288 JMP 545% ;OR E62E WITH BASIC 4 
dditional eode can be written to ie 

ter the address in ($90) to $027A, and to change it back to its morma! value; or it 
an be activated by changing [RQ in the monitor to 027A or whatever other address 
iis code ig put into (it it relovatable}. LIST, for example, is stopped by the routine, 
ad ean be continued at will. BASIC 4 has routines of this sort built in. 


3.3 Other ROM routines. 


isassembly of ROM routines CBM ROMs are easily disassembled, and (except for 
ASIC t) have no peck protection, Chapter 15 has a guide to ali CBM BASIC ROMS so 
ir issued. Nevertheless it is not very easy ta uge such routines, since they are all 
with few exceptions) very complex. The next page has an example of a disassembly 
yf ‘OPEN') written out in English; this sort of translation is essential if a ROM rout- 
ie is to be used and reused. Less detailed examples include the flowchart for PRINT 
in Chapter 5) and for the machine-language monitor (in Chapter 10). Unannotated 
isassombler listings are difficult to follow. Many important routines are collected in a 
imp table near the end of memory called the ‘Kernel’.® [t is possible to deduce their 
inctions by looking through ROM for calls (i.e. JMP or JSR) to them; for example 
FE4 is GET. The kernel routines and their juisp addresses for all ROMs are listed at 
ie end of Chapter 15; the entry points for BASIC keywords are noted in Chapter 5; 
ad the machine-code monitor and its subroutines are listed in BASIC 4 sequence, 
tarting at about D400 in the BASIC 4 column of Chapter 15. 

There are fac too many routines to cover exhaustively. Let's consider 
ET ond PRINT. 
ET in BASIC ia closely similar to CET#, whicn, however, cally a routine to set the 
put file number. In effect, the device number fa usually zero for GET, and may be 
or 2 (tape), 3 (sercen), or 4 or more with GET#. In any of theaa canes, JSR FFE4 
ches a single churacfer into thy Accumulator. If it fa the null byte, no character Is 
ssumed to have been found. GET also, of course, hag an assignment routine, ao that 
&T X$ not only fetches a character, but causes X$ to be set up with length 1 to hold 
1e character, On dissssembling FFE4, we find that ST is set zero and the device num- 
er Is checked. This {s a standard feature of CBM 1/0: in OPEN on the next page, 
co have LDA device numbur; GEQ or BNF tests for the keybotrd (device #0), After 
iis, A is compared with #3, if equal, the device is the acrcen {device #3); Hf the 
irry flag is clear, one of the cassettes (#1 or #2) is asaumed; and if the carry Rag ie 
at, the device number exceeds J, and may Le (for example) 44 (printer) or #8 (disk). 
o, Ly coutrolling the device number, we can control the device which FES gots Its 
haracter from, The pause loap, above, sssumen the daput device la Ure keyboard, 
hich ia the usual default value, By dlsaasempling, we can see (het SAF holds the 
eviee number ($0263 in BASIC 1); wo can alno find (for example) that the cursor's 
raiiion on the sereen, and whether or not it Gushes, are contrelinbla when the scrsen 
Fused aw an input device. Similarly, assuming a file ts apen to tt device, we cen get 
haractera (ny machina code much fauter than fa possible with HASIC, attleast with disk 
wince tape will be slaw da nay case). There js a peanword repting on the next paygn; 
YS 624 woite untill 4 pasnword Twos been entored, using FRE4 ao it dan't echoud to the 
rraon. EE it da wrongly entered, RESET is called, Mere oophjaticated veralons allow 
everal attempts to be mule, and prompl the user with ‘Eeter pasoword'’, but tho 


Comandure Literature, et the time of weating, aseesn to have adopted 'Rernal’ e# its 
ffictal apelting, 
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13: Using ROM routines 


EXAMPLE OF ROM DISASSEMBLY: 'OPEN* 


JSR inputs and stores logical file, device, and secondary address parameters. 
LDA logical fle number ; 
BEQ print ?7SYN'TAX ERROR rejects logical file number 0. 
LDY #offset for FILE OPEN message in table $F000 ff. ; 
ISR checks table of up to 10 logical-file numbers for match with accumulator. 
BEQ print ?FILE OPEN ERROR if the file number exists already. 
LDX number of open files. 
LDY #0 
STY status byte ST. Sets ST to oO. 
CPX #S0A ; ; 
BEQ print 7TOO MANY FILES ERROR if X is 10 at present. 
INC number of open files. 
LDA logical file number, é 
STA File table.X. X still holds the previous value, je. 9. 
LDA secondary address ‘ : 
ORA #$60 sets bits 5 & 6. Secondary addresses>¢5 repeat earlier values. 
STA secondary address: stores the result, . 
STA Secondary address table, X. Also stores the result in the second table. 
LDA device number Be accel : 
STA Device number table,X. Finally, stores the device in the third table. 
BEQ RTS. if device number is @, i.e. keyboard, file is Now open. 
CMP #3 ne 
BEQ RTS. {f device number is 3, i.e. screen, file is now open. 
8CC +3. Branch is taken if device is 1 or 2, i.e, cassette. ; 
JMP sends name string to IEEE for device numbers >3, usuall disk . . : 
String is usually of form "@ filename, typ¢, mode” and the recetving device 
processes it. If the device is present and answers, its file will be opened. 
Tape: 
LDA secondary address 
AND #0F removes bits 5 & 6 again, leaving secondary address=0,1, or 2. 
BNE Wl. Write tape if the branch is taken, that is if secondary address=1 or 2. 
Read: ’ 
JSR priits PRESS PLAY and waits for caasette key (unless a key's down now). 
ISR prints SEARCHING and, if name has non-zero length, FOR FILENAME ..- 
LDA length of name 
BEQ T1. If a name's not given, loads the first header. 
ISR find a named header matches the first characters of the names — 
BNE T2. If the accumulator holds 4, the header wasn't found; in this case, 
print ?FILE NOT FOUND ERROK, abort files, and if in program mode 
print IN LINENUMBERK with the current tnenumber, 
TLJISR find first tape hender (i.e. or next on tape) 
BEQ prints "FILE NOT FOUND ERROR, as before, !f no file can be found. 
BNE +8 unconditionally branches to T2 when the file is found. 

WLJISR prints PRESS PLAY & RECORD and OK on cassette key depression. 
LDA #4. Indicates the type of file (date. 





JSR writes tape header Write. 
T2 20 byte routine which sets the pointer to the cnasette buffer to 0 for 


write, 191 for rend. [f writing to tape, puts #2 into the zeroth. byte 
of the buffer as a marker, 


Ola AOM BASIC ? differs In some ways from this schema, which closely follows 
both BASIC 2 und BASIC 4. There Ina rather miabuding appearance that tape 
handling predominates in OPEN, because the [EER processing In done cisawhere. 
OPEN in one of the commands frem the ‘kernel’; ita address jp $FFCO, from 
which the following addresies are jumped ta: 


KOM entry points: 


BAdIC £: $F52A (82784) 
BASIC 2: SF521 (82753) 
BASIC 4; $7380 (62816) 


= uct Ae er NES ee 
wey Ree area an eeeek geet, ctor emu = sem ar pee 6 aS oe oe RL RMR AF . 
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general idea should be clear enough 027A LDA #00 {ERASE KEYBOARD BUFFER ... 
from the example: O27C «STA 9E 30263 IN BASIC 1 

The loop construction in 0272 JSR FFE4 
OR7E - 0282 is a standard wait-for~ 0281 REQ O27E ;LOOP IP NO ENTRY 
entry. exactly analagous to BAS{C's 0283 CMP #41 

ea 028% BNE 0291 ;RESET IF NOT CORRECT 

100 GET X$: IF X$="" GOTO 100, 40,7 Jon preg 
and usable because JSR FFE4 acts O28A SEQ 0297 
like LDA, setting the zero flag when O28C CMP #42 
a zero byte is loaded into A. The 0282 BNE 0291 ;RESET I? NOT CORRECT 
'pnasword' ig ‘AB’; in practice, 4 0290 RTS 
longer routine can input tonger 0291 JMP (FFFC) 


passwords; the resulting program 
will be more compact if it keeps the password in a table, and relies on indexing rather 
than the straight-line style of programming here. : 


PRINT can be directed to any output device in a way analogous to GET. The kernel 
corresponding to FFE4 is FFD2; on disassembling, this has a very similar device num- 
ber check, but its location is $B0, not SAF, as this is the output device; its default 
volue is 3, since the usual output device is the screen. ($0264 is BASIC L's location). 
Operation is the opposite of GET: a value is loaded into A, the routine called, and the 
ASCI! equivalent printed. Chapter 15 has @ lot of information about this. PRINT calls 
this routine in a loop when a string is being printed to the screen; each character is 
simply loaded, with the LDA (Zero-page).¥ command, and individually output. This 
method may be easler than relying on CA27/ CAIC/ BBID in ROM 


Demonstrations which use various ROM routines A short selection of programs which 
use BASIC routines and demonstrate their operations follows. Most ROM routines refer 
to standard zero-page and other locations; skilful use of ROM therefore usually in- 
volves a certain amount of disassembly to investigate the most important parameters of 
a routine, plua some searching for routines which will do as much work as possible 
given minimum preliminary work. See for example POP and VARPTR in Chapter §, each 
cf which largely relies on ROM routines, the first on RETURN, the second on LET. In 
both cases the actual working of the ROM routines doesn't necd to be understood fully. 


(i} ‘Receive line from keybourd'. This is an important routine, used, among 
other things, to take in lines of BASIC and combine them inte a program. To watch 
it in operation, key in the "Display bytes using [RQ‘ program (2 pages back) and set 
it to display 80 bytes from $0200, which is the start of the input buffer. (BASIC L's 
buffer starts at $0A). The buffer is 81 bytes long; when a line is input, a zero byte 
is put at the end, so 91 bytes are needed to store a line of 80 bytes maximum. In 
the machine-language routinc to show how 
thls works (right) [ have separated oul the 
two functions of Inputting a line and token- 
ising It; a leading space causes tokenivation, 
hoe leading space inputs the line without 
changing It. Both proceases can be watched 
as they take place. (Note: use lower-cuse 
mode, f.c. poke 59468,14, to enaure alpha- 
vetle characters are readable). SYS 626 prints a Mashing cursor, and awnits Input; 
when Return ia pressed, the line ts Input, as you will be able to aug. When the line 
includes a leading space, you wili algo see the tokenisation process occurring. 


{il} Get Hnenumber from BASIC line!. To unve space, we'll consider BAS(ICs 2 
and 4 only here. On exlt from Mtuestve line from keyboard’, X and ¥ hold 4FF end 
#01, They are set to point ta MHF. We 


can use these values with HASIC's GEITCHH O3394 ISR C4dF/ B4E2 ;GET HASIC LIKE 





O334 JSR C408/ C46F/ 8422; BASICS 1,2,4 
0330 LDA 0200 

0346 CMP #20 

0442 BREQ 0345 

0344 RTS 

0145 JMP C4eb/ C495/ B4FB; BASICH 1,2,4 


routings a« shown, with the ‘Get Hnenumber’ 033D ATX 77 

routIna. The effect of this in to stor: the Oj4¥ ary 7a 

number in ($£1); # no aumber Is found, or 034) JER CO79 ;GETCIA AFTER $O1FP 
the number in zero, ($11) hulds #0. Ta © 9 Ocl4d JER CH?3/ BAYA (CRT NUMERALE 
prove it's worked, the finul audroutine G347 LDA 12 

printa the value of ($11), uslay another 0349 Lox th 

ROM routine which printa 259°A * Xx, 0348 JSR DCOG/ CFAZ {PRINT NUMBER 
Now SYS 928 awalts 8 tine, and on Return O345 RTS 


prints the value of Ita leading integer. 


HPN ERCP EMR EA ETI Br ON NTI arti Rm 8 my OTe AIEEE TEC ee Coe am conga * 


i ee ce a 
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(ii} Search BASIC for iinenumber. 
GOTO, GOSUB, and other BASIC operations 


use the subroutine C522/ C52C/ BSA to 
find a specified linenumber, Confining our- 
selves to BASIC 2 and 4 (BASIC 1 uses 
different storage tocations), this machine- 
code (right) hunts BASIC for the line- 
number in (033A); if found. the carry flag 
is set on leaving the ROM routine, so this 
program uses a location to register whether 
or not a line actually exists in BASIC; this 
is 033E, which is zero when the line exists, 
but #FF otherwise, (033C) holds the pointer 
to the position of the line’s start, Because 
both ($11) and ($5C) are liable to be over- 
written, they are saved in these special 
locations, but machine-code programs usually 
will make use of the valucs without needing 
to do this. The short BASIC program which 
follows, entered at the end of any BASIC, 
lists ail the linenumbers and their positions: 


62500 FOR L=0 TO 64535: POKE 826 , L-INT (L/256) 256: 


033A 
033B 
033¢ 
033D 
O32E 
Q33F 
03442 
0344 
Q347 
0349 
034B 
OI34E 
G351 
0353 
0355 
0358 
O35A 
35D 
O35E 
0361 


LDA 
STA 
LDA 
STA 
LDA 
STA 
JSR 
BCC 
1.DA 
STA 
LDA 
STA 
RTS 
BEC 
RTS 


62510 SYS 8312; IF PEEK(830)30 THEN PRINT “LINE” L 


+ 256*PEEK(829): NEXT 


(iv} RUN. This routine (at C775/ 
C785/ B808) has four fines of machine-code 
only; one jumps to RUN, two jump to RUNn 
where n represents a linenumber, and one 
is a Dranch to separate the two, depending 
on whether RUN is an isolated keyword or is 
followed by a number. The machine-code 
program (right) shows how the option which 
runs From o linenumber can be mimicked with 
the linenumber search program. Note that 
RUN assumes CHRGET points to the zero 
byte preceding a line: for this reason it is 


STA 
Jur 


necessary to subtract #1 from the pointer ($5C), which 
#FFFE plus the carry Mag to (5C) and storing the regult in (77). 


(v) Memory move, A routine at C2E1/ 
C2bF/ B457 Is one of several in BASIC ROM 


0334 
338 


which move blocks of memory; this one is used 033C 


to open space {n BASIC, so ROM calls which 
make use of It move memory from a lower to @ 
higher point. The demonstration routing fills 
the sereen (40 columns - 54000-S$43E7) with 
bytes from memory, starting fran the location 
stored in (OFA). ($50) Rolds this value, 
($57) has to hold the top of the areca to he 
moved + 1, so this is eaivuisted by adding 
#38. Finally ($55) holds the top of the area 


_ te be muved io 4 1; this jy S47E8 in Che 


exanple. This ean of vourse be modified to 
mave other blocks of RAM than those of 
length WIRES hyles, und inte other locations 
than the seroon top, for exermpie by poking 
vations fram BASIC. 


03920 
0240 
0342 
amid 
0346 
0349 
0343 
0340 
O34F 
O3oL 
Q333 
a355 
GI37 


Che 
LDA 
STA 
ADC 
STA 
LDA 
BTA 
ALC 
STA 
LDA 
STA 
LBA 
STA 
JMP 
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;LINENUMBER LO BYTE 
;LINENUMBER AT BYTE 
{POINTER TO LINE LO BYTE 
;POINTER TO LINE SE BYTE 
;LINE FOUNN/ NOT FOUND FLAG 
033A 


O33 

C52C/ BS5A3 ;BASIC 2 OR 4 
O35 ;NOT FOUND IF C=O 
sc 

033 

SD 

0133D 


O33E ;FLAG = #FF IF NOT FOUND 


POKE 827,L/256 
“STARTS AT" PEEK(828) 


;SET ($11) = LINENUMBER 

C52C/ BSA ;BASIC 2 OR 4 

gx1T ;NOQ SUCH LINE 

sc 

#FE 

77 

3D 

#FF 

78 

C7BA/ B8OD ; RUN FRCM LINENUMBEF 


the program does by adding 


;BOTTOM OF AREA TO BE MOVED 


O33A 
“x 
Lp) 
ST 
6338 
5D 
#o3 
58 
WEB 
55 
eRe 
34 
CapF/ B357 ;BASIC 2 OR 4 


Memory movi routiees aren't a6 simple as they might appear at first aight: the 
problem oneurs Sf a regien te tee moved overlaps with the regio It is to ba moved (a. 


Suppose tha first four byled of ARCDEF are tu tas 
If the monmery unave operntes by taktng bytes from the left and warking to 


by CDEP. 


thoved to The region new oceupled 


the vight, fie result wil he ABAH, not ACD. Vhe order, here, ahould be right to 


oe ERNE EN ES aE mle RR RR OY RE PR RE A SI A= 
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left. The short BASIC routine is a bug-free example of what is needed. If you are 
not aware of this potential problem, baffling errors may result, 
REM EE ESE EEE Ee RAMEE REARS REESE EREERE PERE ER ER EHR EE 


[EM # MEMORY MOVE IN BASIC, * 
REM ® PARAMETERS: SASSTART AQDRESS OF BLOCK TO SE MOVED * 
REM «* EA= END ADDRESS CF SLOCK TO BE MOVED + 
REM ¢ TA= START ADDRESS OF BLOCK TO BE MOVED TQ * 


EM RARER SEE EERE EEE ERR EE ERE HR HERER EER EE EEE A ERR O HEE RE 
REM 

IF TA>SA AND EA)*TA THEN 1020 

C20: FOR t = SA TO EA: POKE TA+Ce PEEK (1)¢ C#Cet: NEXT: RETURN 

CeZA-SA: FOR I * EA TO SA STEP -Lt POKE TAeCePEEX (1): C=C-1: NEXT:RETURN 


(vi) String cumparison. CF1E/ CFi0/ COCE is the start of the string comparison sub- 
routine; its parameterd are listed in Chapter 15, Like many ROM routines - and this 
feature serves a3 a bridge to the next section of this chapter - the relevant part of 
the routine is embedded in other processes, not separated out as its own subroutine. 
For this reason, the routine must be relocated into RAM and modified there. If the 
central part of ‘String comparison’, |.e. after the parameter-setting code and up to 
the exit from the comparison loop, is relocated, it may be followed oy RTS and used in 
isolution. In this way, it is possible to confirm that X is set to sFF/ #0/ #1 according 
as the first string is </=/> the second. SORT (Chapter 5) relies on the relocated 
comparison routine for its operation. 





13.4 Examples of modified ROM routines. 

13.4.1 PRINT USING, The number formatting buffer, in which numerals are placed 
for printing after conversion from the flouting-point accumulator or elsewhere, extends 
roughly from SO0FF to SO10F. ‘Display bytes using 1RQ' can show how this buffer is 
used in practice, and the table below gives specimen results fron a variety of number 
outputs, including string conversions, calculations, and simple print statements, The 
notes on PRINT USING in Chapter 5 explain how the normal number printing routine, 
which is made up of three consecutive subroutines, can be copied. bul with the add~ 
ition of an extra routine to alter the buffer from the way it appears in the diagram to 
a new, formatted and justified arrangement. 





EXAMPLES OF NUMSER FORMATTING 


WHEN BUFFER CONTENTS: 
PRINTING : OFF tO 101 102 103 104 105 106 107 108 1059 104 10B 10C 10D f0E 10F 

















































] sp 9 @ Unchanged ........5. 
aS sp 4 5 @ 0 0 09 0 9 G %QG Unchanged ... 
- 24.1234 sp 2 4 . 1 2 39 & @ O @ Unchanged ... 
999 999 999.1 sp ¢ 9 9 9 9 9 9 9 9 @ Unchanged . 
999 999-999, sp TE + TT @ FO TF Unchanged. 
spo4 3 8 9 . 9 & 4 1 1 @ Unchanged ... 
. 6 9 3 1 4 F F$ B OB Unchanged... 
ASC{"T") sp_8o4 @ 69 6 oO 0 8 8 Gt Unchanged ... 
Tie sp 2” | 6 6 €° $ FG BY Unchanged ~.. 
TIs* o 3 & 4 @ Unchanged .........- 
STRS{ 94) 4 @ 09 0 O08 8 @ @ @ Unehanged ... 
STRS(1/3) spo. 9 3) 3 3 9 9 8 4 9 8 Machanged ... 
STR3{-pl) Te BO Unchanged 2. 

- 009 sp 9 E - @ 3 9 O09 8B 0 OG Unchanged ... 
1E-23 - 41 E - 2 3 @ 0 O08 08 8 Unchanged ... 
32345678.9 sy? 63 lA SK hGH 8 Unchanged 1. 
123456789 “sp 02 °374§ &§ €6 7 °B° 5° OB Unchanged 07 

SIN( pi) wo 7 . 39 FY & 5B 9 DO F E - 1 6 @ 
170009 G10 19 i] t 1 1 1 1 i] 1 1 € + t 0.68 
0 » oO 98 9 0 8 8 @G Urnichanged .,. 











*These values are specimens only 
‘O represents the sutl character 


cs ealaadietitica Rherhidset tata i: te’ cscmn aeons e tnbiecn hada natadletto tment delice tania a hain Da BT anole eae ena Retaeeieladandimt ieee 


13: Using ROM routines 


Programming the PET/C8M -357- 


PRINT USING is too long to explain fully here; the buffer-editing routine formats the 
data in either floating-point or integer form, by inserting or dropping the decimal! 
point; it also checks for the presence of E and the null byte, among others, and has 
exits which it takes if a number appears to be of the incorrect form. it makes no 
attempt to format a number containing 'E', for instance. On teaving the routine. ($61) 
is made to point to $0100, the start of the buffer, from which point the string-print 
routine takes characters, printing them until the null byte is encountered. 


13.4.2 LIST, Chapter 5 has a BASIC lister which generates program listings in which 
the cursor control characters appear as [DOWN),[RVS]. ete. Apart from the problems 
of lower-case listinga with CBM printers, this is probably the most wished-for feature 
of LIST. It is fairly easy to implement, once LIST has been moved from ROM to RAM. 
because LIST is a comoact routine and a patch is quite easy to put in. A BASIC 2 
version (see below), called by SYS 7*4096 or SYS 24672, lists in exactly the same way 
ag the ordinary LIST, except for the special characters; these are held, with their 
equivalent output, in two tables after the machine-code. This sort of rouline must 
have a control over the length of a printed line, since any line with many $pecial 
characters in it will be printed out to a length which may cause some characters to be 
fost. The annotated BASIC 4 version shows how & BASIC loader can improve a pro- 
gram's versatility; it relocates its code inte any BASIC 4 machine, and allows casy 
changing of the target characters to be specially listed. It too has a linelength contrat; 
a short specimen shows the sort of effect which can be achieved. 


at 
Po IRQ SR AC XR YR SP MACHINE-CODE LIST FOR BASIC 2. 

-3 0401 £62E 32 04 SE OC Fa : 

Te 7000 A9 G1 85 5C AD 04 85 5D SYS 7*4096 runs this routine, which tists 

+t 7008 AY PF 85 11 85 12 Ad Of the entire BASIC program in memory, 

a aie ce oe By 35 bal Aa 20 wy starting at $0401. It processes characters 

+: 7021 Ca Bi 5¢ cS 12 00 04 ES within quotes. There are (here) eight 

+t 7028 41 FO 02 BO 2c Bd 46 29 ¢haracters which are specintly deatt with; 

nt aa36 re BA s ag oe nn ae ie they are stored in a table sturting at S70EU. 

+t 7040 09 49 FF 85 03 CH FO 11 The corresponding output is held in another 

ee cere + ae ye ere ge table, starting at S$70F0. So character $11 

a joes 63 ae is s3 1) 30 Cs FF (17 decimn!), the first item in the first 


table, appears us [POWN], which is the 


+t 7068 7# AA @4 46 AO FF OCA FO i ‘ in the second table. 
*. 2070 OH CH BI 92 CO 10 FA 3 first item in the second e 

ae fe ll are ae ae A zero byte has bren used to terminate 
ae oe Be a3 Gb 60 GEO HA 03 printing, so an output item can huve a 
+s) 7090 CA 10 KH AE KY 70 40 maximuin Jength of 7 only. 


7094 70 BA OA A OA” AB BD cur) 
ve 29 BA 7U EX Uy OPEN 4,4;CMD4:S¥S7*4096 

7044 FS AE KS 70 Gtr 38 70 06 
rt 76H0 20 £2 CF AY Ge Ht Ad 70 then PRINT#41:CLOSE4 Ista to n printer. 
+t) 708A 40 EA 48 26 45 cA ER #4 
+t) ©7000 70 AD AA 7) CUMALEU G2 
ry) 7008 68 60 20 BO 70 BO CAFE 
ot 7apnh 20 CA FD 20 CA PD FF 
Pe ee Yip 


ie 
J 
o 
> 
o 
e 
2 
™ 
o 


This reutine ts sultable for a 32K machine; 
see chapters (3 and 24 for information on 
relocating iachine code. 
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er fURIQIT Es Vlg * 

ot yea OG OG G0 35 4 

otf durty lb ad Gr oe 

et yP TPR D Sb ee ate tn wh uf 

esl P98 Sit qu 4F 4 do ‘dl L000 

er) PIGH ha G2 a0 4) da na Gu ug Caontels Length ot Une = 96 dacarter. 
ete Tit SB ba Sa Sh eu fH GA uty 

at) Pte us ad Seu! aR ou OR oe (Fae on tb seotumn bat only th ange tre lar we $14) 
asf FIZ0 hi 45 a dh At PG NO 

eek Fl2N al 4 au ae 4 tu a 

on 

at 


. 
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ICATING LOADER FOR SPECIAL ’LIST’ 


LH9+ Or Uitte 4A, LBS 302 133, S21 69-0, 193-49, 193- S1- 193-55, 94 

2A9s 19433) 9201694513999) REM 1) LOWER MEMORY, 2) SET LINENUMBERS 
LDDs BS 1OFr Be 221 p — ABP e DAD Fe QI sy LHe 24Gs L746 -BEis+ Fos F404 155510 
10+ 10¢1700) 189s 249" 240+ be G2p - 2975 232+ 208s 2451 1724p -390+ 2s ~ 437 

Op 320 P28 18S: 149s As L411 BS h2 Fb, Oe 726 32s 70+ 187, 298s - BSL 179s -F51, 2048 
$02 240726 104+ PSr B24 ©3072 169s Se L415 5b7125s 169492: 32-219 
258.204) Shs L256 POGOe 246s 1042 96 


BATA 
DATA 
DATA 
LATA 
DATA 
DATA 
DATA 
du REM 
2 04M 
22 REM 
OS ulm 
04 KR 
5¢ T 
50 L @ 
OO REM 
01 REN 
32 REM 
02 KEM 
24 REM 
35 REM 
10 X 4 
20 FOR 
30 FUKE Jy 
40 X = XL ¢ NEXT 
60 FOR J = Lb OL + 24+ READ X ¢ POKE Jr Xs 
70 FOR J = L + 164 TO L + 251 
BO READ X%: EF X¥<(O THEN Y=x%+Ts 
90 POKE J + X% 
00 NEXT 
30 KEM 
51 REM 
52 REM 
33 REM 
54 REM 
40 -.EM 
61 FEM 
55 POKE L+1i6+ 53: REM CHANCE BRANCH MESTINATION {VALUES 00-7F> 
66 FOKE Leil4d, 49: REM CHANGE SRANCH DESTINATION (VALUE FF =P I} 
OH? vue Letl@r 45: KEM CHANGE BRANCH DESTINATION (VALUES 80-FE> 


POEerrerTrree tr OTe re See re ee 
#* USER-DEFINABLE LIST FOR BASIC 4.0 24 
PwUUPETE TCC TET CRE Lorre ESS ey 
4 


+ REM CURRENT TOP OF MEMURY 
a REM ASSIGN 513 BYTES 


PIEK(52) + ZS6#PEEK( 53) 
T - $13 


PUTTUTTTVURTOVAT TOTS ULC Tere SI TSO ee eek lial 
* BASIC 4.0 MEMORY-MOVE OF ‘LIST’ RUUTINE INTO RAM. * 


* HOS? - $BS60N (46679-46813) » 
Pereraevrrrrereri: tet ret limes rer i Se TE es Dt eee i illicialel 


is) 
Jos Lb + 25 TO L + 159 
PREK €X4495579) 


tREM STARTUP ROUTINES 
+REM PROCESSING ROUTIN 
XB27/256: Z2¥-XB#256) POKE JpZ: JaJel 


NEXT 


ERA KHEAKRRAL EMER RA EEE EEE EH ROE ERENT REE HH RE 


#* CHANGE BRANCH AND JSR COMMANDS IN ‘LIST’ TO RUN GWN ROUTINES # 
Pererrerrrervrrrrrervrrir tT Title tir tigi it tiie tte hd oe tek 


*# SEARCH BYTE TABLE ROUTINE 


é9 FEM 

70 REM ® CRLF ROUTINE 

71 REM 

75 X% * T-307 » REM CRLF POSITION RELATIVE TO TOP OF MEMGRY 

76 AE 0 X/256 + Ze X - XX#256 

77 VtME Lets 20 COKE Letds XX 

79 KEM 

80 REM * PRINT BYTE ROUTINE 

81 KEM 

a5 xX © T-297 1 REM PRINT CHARALTER ROUTINE RELATIVE TO MEMORY TOF 
Be XK = X/256 |Z =e X - KRe256 

8? FUKE L474, Zot POKE Le75, XX 

BB FOKE BelS4> Zi POKE L.+i57s XX 

00 FEM 

Ql REM ADEM TEEPE ED EERE HEHE RE OEE PEP HEH SOK SESR ELEN SHAE RED 


HEM © PUT NW) LOWFR TOP OF MEMORY INTO MEMGRY POINTER ROUTINE * 

TMT tt itt itd 

fEM 

MR « L/2546 #2 = L = XX#255 

PIKE Loo 2 + Zt POKE Lo + Ft X68 

HEM 

FEM Se eek ed HO OEE EE ERHA EEN EO EEE OFERE EEE SOPH ETH EEH PENH EUTHE ASAE ES ERP 
Ree « USER'B TABLES OF BYTES ANT GUTPUT (£G 1357 PRINTED CLEFTSS ° 
vEM ® CAN BE CHANGED SUBJECT TO MAXIMUM OF #4 ITEMS OF LENOTH 7 * 
REM AOS FER LEO E DROSHA EER HEEEDRAE HEE TSEHEOHEEEEEGAPERGUEERHOSSHEPSEEO HS 


92 
03 
04 
os 
io 
00 
oL 
02 
93 
04 


av 
POET NT YIN TOIT Cor rm RR RE RE I CRE I 


ow. 


1408 


1410 
1420 
1430 
1440 
i450 
1440 
1470 
1486 
1490 
1500 
1504 
13502 
1503 
1504 
1310 
1520 
1530 
1340 
1550 
1540 
1570 


1580 
4900 
4999 
S000 


SAMPLE SHOWING EFFECT OF CHANGING LINELENGTH (#24) + 


rem 


TA re anal AR aT RR I a i Ae Are ee 
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DATA TABLES) $0+47+1@-49s 29) 145+ 146) 147+1570160+ 2551 REM 10 =ITEMS IN TABi 
£ 

DATA CDOWN)» CRVS1» CHOME)» CRIGHTI» CUPI« CRYSO}, (CLRI+ CLEFT] + CUSFH: Jy LPL 

FoR J = 1 TO 1£9 READ X$ 3 JF X% ¢> “TABLES” THEN NEXT 

REAL X% + REM NUMBER OF ITEMS IN THE TABLE 

POKE L + 168 » XX - 1 : REM SETS LOOP IN m/CNbe FROM O TO XXK-£ 

FOR J Lh + 254 TOL + 253 + X% 

HEAD X ; PIKE oe X +: NEXT 3 REM BUTLD TABLE OF BYTES IN MEMORY 

FOR J « L + 269 TOL + 268 + X%xX#8 STEP & 
ViiKE Jax, 


NEXT 


ASC(MIDS( XS) Xe bd) 1 


READ X$i FOR X # 1 TO LEN (X%) 
POKE J # X + O8 NEXT 1 REM FOXE NULL TERMINATING BYTE AFTER EACH 
REM 


REM A6HH ERE HEO ARSE EE EEEE EEE EERE EE EERE EERE ER ETHER EEO EEE EEE EERE 
REM * PRINT INSTRUCT TINS AND ADDRESSES * 
REM eee RARE RRR E EER EE 
REM 

FRINT "CCLRICKVSICDOWNIC DOWN] ROM4 LIST BY RAY WEST ~ 

PRINT “COQWNILRYSILIST SYS, CIEFT1“: L+t? 

PRINT “CDOWIFOKE“+ Lez2? 4 "TO CHANGE LINELENSTH™ 

PRINT "CDOWNICDOWNJSAVE FROM” + EL ¢ " TO” 5 L¥5i2 

PRINT ~ (8° #+. X=L: GOSUB 5000 
PRINT “ TO $7 #2 L#X+512: COSUB 3000 : 
FRINT“CDOWNISECURE IN MEMORY WITH SYS” 
MURY 
FRINT"CDQWNICIICWNI “3: 
END 

KEM DECIMAL TO HEX CONVERSION 

LeL/4096: EGRE*4TO4; L£=Ls PRINTCHARS (48-+L2-( L599) 87 50 Leloe(L-LE) NEXT: REPUS 
N 


PRINT)" 
K :PRINT “WHICH LOWERS TOP-OF-ME 


LIST 1410 


10 DATA 167:%:133,-45 
+133) 50-133+52, 1869 
90-133,49) 133 S$le1 
33+ 3a+ 96 

11 DATA 149) 1+133592 
9169+45+1393+ 93: REM 
1) LOWER MEMORY» 
) SET LI£NENUMBERS 

12 DATA 142:-350, 162 
9 Bs 22he -259+ 29009 
202) kOe 248. 174, -35 
Or 76> ~440+138,10 


Fs 


ACE The TRACE routine In Chapter 5 Is another application of LIST, in 
thls case written to display single lines at the screen-top. [t operates by intercepting 
the GETCHR routine: this is a standard technique, explained in full detail in the next 
Chapter. its controlling keya are determined by the keyboard decoding tuble, and 
apply to BASICs Land 2 and the 40-column BASIC 4. There Is insufficient space to 
Include two more versions, 60 BASICs 1 and 2 only eppenr in TRACE In Chapter 5. 
The flowchurt of the routine (see next page) showa how CHRGET haa intermediate 
{natructions: this version of ‘trace’ deca not distinguish between statements, but by 
Hnenumbers, #0 that a Une is listed for ay long a4 it la being executed. The trace Is 
turmed on by pressing KVS, and off again by pressing the sane koy, go keyboard 
contrel of the routine ly wood. A,X. and Y ary saved and restored, BO CHRGET's 
running lin't disturbed, The status flags are wet ata Inter Klaga, and need nut be 
gtered. Note that a singie atep bs available; when the trace Is on, ‘2! caukes a HANIC 
ine io be executed, and no further Hnes are exuculed untl elther =" ls pressed ngain, 
or thy routine ja reset by the spred change cammund, '[" followed by a number from 
0-9 Lines ars executed every 5 seconds with 0, dawn to every 4 second when 9 Is 
chowen, This, however, is overridden by tha space key, which removes (he action of 
the delay loop. aud teaves through the program very rapidly, LIST ts not very ensy 
to Inearporaly in prageunsa Hke this, Gecause it usea many erre page lnoeatlons which 
are normatly allocated for athee purposes. Thhe ly probably the ronson why LIST is not 
Wlowad in program moda withunt terminating tha program run. My vorshit of Upacn 


13.4.3 TRACE. 


. 


oe ee ere ites eR IRE, ELAR net A Smee * 
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lesteps this probiem by saving the zero-page, and restoring it when LIST has done 
work. This approach also enables the horizontal and vertical screen positions ta be 
‘tained even after the cursor is homed and the top of the sereen cleared for LIST. 
ere is insufficient space for full documentation or explanation here. However, the 
mory map of the routine is arranged like this: 

{i} Initialisation routine to alter CHRGET and lower memory pointers. 

(ii) Switch-off routine to restore CHRGET. 

(iii) Space for 9 bytes. These are: A,X. and Y¥ storage; Trace flag (#0 off, #FF 
); Step flag (#0 off, #7F on); current tinenumber, stored as low byte then high 
te; delay parameter; countdown for delay loop, starting frum delay parameter value. 

(iv) Routine es in the Flowchart, excluding ... 

(v) LIST routine, slightly modified (e.g. not to print crif at the start). 

{vi) 256 spare bytes for the stored zero-pages. 


from CHRGET 







RVS key 
pressed? zes 
Switch trace 
No flag 
Ta trace No 











flag on? 










{ key for 
speed change 
pressed? 









Put single-step off 
ET delay paranete 
from keyboard 






inenunber 
= stored 
value? 


Set step fla 
Clear buffer 


You 










Singlo-ate 
tlag on? 


lay aeing 


De 
paramoter 


Btore new Line~ 
auaber; LIST new 
ling on acreentop 


ot 


E A,x,@¥% 
{heck to CHROFT 


RA a eT YE a Ta TA AY RCI MAE PTI RIERA SIS IIIS aT SWARMS R= IS = *S 
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CHAPTER 18: EFFECTIVE 6502 PROCRAMMING 





14.% Assemblers. 


We have seen the improvements in machine-code readability brought about by the use 
oO: opcodes, and by the use of hexadecimal notation, over the fundamental @-bit binary 
storage of this system. 


consider what is involved. A diagram on the next page illustrates features found !n 
most assembler listings, without representing any one actual assembier's output. Note 
that the object code is identical to that produced by a simple disassembier. This is not 
surprising. since the same fundamental dnia underlies both approaches and enforces 
some uniformity. The main novelty is the so-called source code. Around the core of 


are punctuated to resemble addressing modes. This code is usually hetd as a source 
file, which is in effect a sequential file of everything labelled ‘source code' on the 
diagram. The job of the assembler is to convert the file into obiect code, an example 
of which appears on the same dingram. Object code is not usually relocatable without 
some effort; it is desizned to be run where it is, from $2000 in the example. The 
great versatility of assemblers is Hlustrated by the command in linenumber 12 of the 
code, in which the starting-point of the assembly is assigned as $2000. A simple 
change to 4=$3000, followed by assembly, generates code identical in its effect, but 
Positioned to start at $3000. In the same way, new instructions can be inserted by 
editing the source file and reassembling; this is far less laborious than attempting the 
same process manually. Note, though, that a source file may be much longer than the 


the total length of the line. A ratio of oetween 29:1 and 56:1 is common. This means 
that long programs of 1K or more are already difficult to fit in RAM and have to be 
separated inte sections. Conversely, disassemblers which generate labels, producing 
& version of source code without comments but with assembler format, are likely to be 


software for the CHM was in fact developed on other machines. 


including the source files LOADERSRC, EDI6SKC and ED328RC, and U-LDI6SRC and 
U-LDIYWSRC, which have useful decumentation) is widely used and has these features: 
it is disk based,*designed for use with CBM disk units and printer, and without 


the set of programs constituting the assembler package. Everything [Is in RAM, as 


this dingram shows: ASSEMSLER [ 


EDITOR 
| |Normat BASIC storage (for 32K) | Screen BASIC ROM 
$0000 “—-~--~- LOADERS ———"—" 













SFFrY 


and several londers. The editor is pictured at the high end of RAM. It actually londs 
into the Jow end and relocates on being run, so it can coexist with the assembler, If 


In and modified from the keyhoard, und saved to disk and perhups printed out, To 


Jtetoerrors which haye shown up. PPE and GET are the commatiaa to save nnd load, 
respertively, (There guy be ad undocumented CPUT whieh stores the tile wiltout 


aUrpilun apocesy. AIL thts is very stamtard jo editars. 

‘The assembler reads a source: Fil intu RAM for uxes a source file already there, 
Buurtingg 10 $2000) and procead4 ta convert dt inte chject cade, which may be stored 
Girecily Inte RAM or saved oon disk anoun object (Ite, The deta aaved Ja farnnattod in 
A manner ainilur tou program file, with the jength of the routine fuilowerl by Its 
atrgthnyg address, mod then all (he data tytea written as tioxadechmal framers, 

The london, ted the obfeet file hist deseribacdk and poke its contents inte IAM. 


Mart uncertaln shether it's (sponsible, ap merely difficult, to uae canmautin tage, 


fa oes a, op te pL I I ee A US NE PRA ES RI NT HY Ah AM HT 


An assembler carries this improvement much further, by allow- 
ing a fully algebraic notation to represent machine-code. Before going into detail. let's 


familiar opcodes is a collection of names and symbols, some of which (e.g. LDA ADRTAB,X) 


machine-code it generates: compare the number of bytes ina typical assembler line with 


unable to cope with long programs, for instance the BASIC ROM. Some widely -available 


EPROMs or other hardware, so there are potential conflicts between ussembled code and 


There are three essentiatly different programa in the package: an editor, an assembdler, 


It (the editor} is loaded and run first. The function of the editor is to enebie the user 
to set up a source file; the Une numbered fornnt is similar to AASIC, lines being typed 


facilitate thia process, line renumbering, Glock deletion, automitic numbering and soon 
are provided. Files can be landed fran disk, edited, and slerecl back on disk, to corr- 


UF the nisctine code program is bediag toaded bigh In RAM, Che law menory luader ts the 


CBM's assembler (issued some years back originally; try to pet the latest version | 
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Ng- ) AD [LABEL/ OPCODE or DIRECTIVS/ GPERAND/ COMMENT} 
wack | DRESS | OBJECT CODE | ~-------- SOURCE CODE-~~---~+------ Seieeteeeaaiae! 











a ; 

4 ;HOUTINE TO AWAIT A EEY, THEN EXECUTE CORRES- 

6 ;PONDING CODE, USING TABLED VALUES 

8 H 

10 GETCHR=$FFE4 ;TYPICAL ‘EQUATES’ DIRECTIVE 

12 2006 #=x$2000 ;TYPICAL STARTING-POINT DIRECTIVE 
14 2600 . FAGE sTYPICAL TOP-QF-FORM DIRECTIVE 

16 2000 , 

13% 2000 20 £41 fF START JSR GETCHR sBTANDARD KERNEL "GET' INTO Act'R 
20 2603 ro rs BEQ START ; WAIT UNTIL KEY PRESSED 

22 2005 A2 02 LDX #2 :TASLE HAS THREE VALVES ONLY 

24 2007 BDO 21 20 LOOP CMP CHALIS,£ ;COMPARE VALUES IM TURN, 

26 2004 FO a5 BEQ FOUND ; UNTIL FOUND OR NOT FOUND 

28 200C CA DEX 

30 2000 10 Fé BPL LOOP ;LOOP FROM X=2 TO I=0 INCLUSTVE 
32 200F 30 EF Bui START ;MEY NOT IN TABLE; GOTO START 

34 2011 80 20 20 8FOUND STA STORCH ;STORE THE ASCII CHARACTER 

36 2014 A TIA BTANDARD JUMP ROUTINE FOLLOWS, 
38 2015 OA ASL A ; IN WHICH THE STACK HOLDS BOTH 

40 2016 AA TAX ;BYTES OF THE DESTINATION, AND 
42 2017 BD 25 20 LDA ADRTAB+1,X ;RTS CAUSES THE JUMP. 

a4 2034 48 PEA ; HIGH BYTE ON STACK ... 

46 201B BD 24 20 LDA ADRTAB,X 

48 2012 4a PRA ; AND LOW BYTE. 

50 20LF 60 RTS ; JUMP TO ADORESS NOW ON STACE 

$2 2020 STORCH #=x*+1 }USES ASSEMBLER LOCATION POINTER 
$3 2021 41 42 43  CHRLIS ,BYTE ‘ABC’ ;SETS UP TABLE OF ASCLY BYTES 

34 2024 29 20 GF ADRTAB ,WORD A-1, B-1, C-2;SETS UP TABLE OF ADDRESSES - 1 
56 202A AQ OO A LbY #0 :START OF PROCESSING FOR ROUTINE a 


Features of a typical assembler listing. 


ee 


ne to use, while code destined for low RAM needs the high-memory loader. We may 
pmmarise the process of writing machine-code with an assembler in three stages: 

Ui) The editor creates a source-file, usually stored on disk. 

(} The assembler creates an ohject-fiie from the source file, again on disk. 

(iil) A loader puts the program In memory; from here #t can be saved os an 
rdinary machine-code routine by SAVE or .M . 
t in mot neceasary to store the Intermedjute stages; it ig merely advirable. Accidental 
148 of a tong progrum, usually when Incompletely debugged muchine-code executes, 1s 
ommon. 

By way of contrast, assemblers may be available In hardware. An EPROM calied 
Vikro' illustrates thia. [k madifles BASIC to include Its awn instructions, which inciude 
command to nasemble; and it uses BASIC's line Input faeciity as an edidny system. 

Most assemisers une the 'two pies’ system, In which forward addresses sre calc- 
dated on a second pasa, To understand why thi, fy necessary, Imngine that you are 
yaumbling the example sbove, and have werived nt line 24. lis wldrosa has not yet 
eon reached, so Ita value (i.e. the value of CHRL1S) 1a temporarily left unfited, if 
here Is no such operand the sssembler prints an error mesos for shoud do}, which 
wobably wilh be one of many. First tine quxemilion without any errors are rere, Unline 
fASIC, which can run fairly suc fully with syntax errors flutted about, Aanonbier 
s Jutolerant of errora Ip its source Cle, Often, removing: errors becomes mo nub gost in 
tanlf, the tumph of fly achleving no eppors! lending the programmer to fall lo 
jotice That the resulting progenm docun't quite do whal it shout, 

Axssomblera vary In the way they aan source code, Sane anauine falrty strlet 
‘Alban formating, and may reguire source ewls to be arranged Uiillys others don't 
tok, boyord expecthag vie or more KpACoed a nupmiontors. For thas cencon, tine 14 





2p RAL RO Mn day Tepe re rem 6 sree enrah  A BPEAY EON A ARIE, eM SN ee ermine ees” 


ey ea Ae RI AE 9 aR OC EOP, ra 
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is refected by some assemblers, because START seems to contain the opcode §Ta. 
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Assembler features. Assemblers for the 6502 and other chips typically have features 
like those listed below, most of which make an appearance in the specimen listing: 


(f) Labels. These mark entry-points to which branches. jumps or subroutine 
calls are made. Often there is a maximum tength of six characters. 

(il} Opcodes, Invariably standard. 

(Ili) Directlves. These commands have a similar effect to opcodes, carrying out 
a single fairly simple function. Often they are preceded by 4 '.', which Is picked up 
by the assembier's parsing; sometimes they resemble opcodes, having three-Ictter 
fmemonics. The most important directives are probably these: 

*or ORG, This sets the starting point or origin form which the object code is 
to be assembled. * has a further use, as a location painter, illustrated in line 52 of 
the specimen, where it reserves 1 byte as a storage location. Similarly, *=*+50 resery - 
es 50 bytes, and .BYTE *-LABEL calculates the difference between the current location 
and an earlier label, storing it in one dyte. 

= or EQU. The ‘equates’ directive is self-explanatory. Most directives of this 
type are collected at the start of source code, where they can be both casily seen and 
checked, and easily altered. 

.BYTE .TEXT BYT TXT. These provide variations on a theme; in some assem- 
blers the functions are combined in .BYTE, in others .BYTE and .TEXT differ. 

.BYTE enters singlebytes into RAM, as these examples show: 

.BYTE 31,SEA, #0200 0091 puts three bytes IF EA 41 into RAM, 

«BYTE COUNT + 1 puts the value of COUNT + 1 into RAM; e.g. if 
COUNT = 4, the hexadecimal number 05 is stored in RAM, 

“BYTE ‘HELLO! and .TEXT ‘HELLO! are alternative forms of the function which 
stores five bytes (48 45 4C 4C 4F) in RAM, and generally sets up ASCH tables. 

WORD takes a I16-bit number, storing it in RAM with the low byte first and 
high byte second. The ‘word-length' of a computer is usually the minimum length it is 
designed to handle, e.g. 4 bytes in IBM machines, 2 bytes in DEC. In @-bit machines. 
‘word’ and ‘byte’ are sometimes used synonymously, but assembler convertion assigns 
2-byte words to the 6502. Line 54 in the specimen listing has an example. Note that 
A = $2024, so A-1 = $2029, and this is stored, with bytes reversed, at the sturt of 
the @-byte table labulied ‘ADRTAB', some of which is omitted by the listing. 

.DBYTE assigns two consecutive bytes to memory in the norma! order. Since this 
can be accomplished in any case with -BYTE#, this directive may be absent. 

.END marks the end of the source code. 

(iv) Symbols. The names (GETCHR, CHRLIS, LOOP, or whatever), including 
labels, are called ‘symbols’. An assembler usuaily constructs a ‘symbol table’ on its 
first pans, filling in forward references from it on the second pass. 

(v) Operands. The ‘opvrand' following an opcode is a symbol or absolute vulue 
punctuated jn the standard way, l.e. possibly including $, % @ to signify hex, octal 
and binary numbers, # to signify Immediate mode, ' for ASCI1 values, and (}, XY. 

{vi) Comments. Often signalied by a semicolon, which causes the assembier's 
parser to ignore the remainder of the line, these, like BASIC REMs, help make o 
progrum readable. 


The CBM assembler. This has .PAGE and .SKIP which turn to a new page and 
skip a Une (for easier reading) tespectlvely. .OPT allows control over the printing of 
information after assembly, .GPT NOLIST, NOERRORS, NOMEMOKY, NOSYMHOLS, 
NOCGENERATE causes onty assembler error messages to appear on the screen, with no 
other output elher to aercen or printer, CUM asaumpler, Uke some othees, allows an 
operand ayntax Including: © arid 9, lo load low and high bytes of 16-bit nddresses. Uf 
MURR MO hud setup (he two bytes corresponding to the value of the symbol Mf. then 
LUA tom Eby ee lowts A aol ¥ with the high and law bytes, 

Assembly cua be stopped with the Slop keys the program then awaits ontry ot 
Mor Batter whieh the aeniar or BASIC is entered, Conditional assembly, where 
yalues sel st assembly tone modify the assembler output, fs voluab.e in producing 
shyhty different versians of ahniine routines, for example to Mt different capacities of 
RAV, Examples aecur in the source code (q.v.), Other apeelal fratuces Include .L0B 
and FILE dieeetivey. LE pernils brary software to be used, which meuns Muil a 
numed) Cle ean be read and asembled into aipther soprea file ilurtng the coura: of ith 
asnipbly. PURE transfers misembly ty another Cie, aa WPMD of seyenenté of cede 
ven be dasembled ong after the offer, Finally. lot's look atoam anseutler Cunetion which 


LN Pe nt AER TN ote mn ee te renee IRE SER RT RAR ATA «= 
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cannot quite be carried out with this assembler. A macro is 4 directive which causes 
an assembler to expand £ pseudo-command into several machine-code commands, which 
carry out the functions of the pseudo-command. An example might Le MACRO INC 
ADDR, which would increment the lé-bit ADDR, by inserting INC #<ADDR/ BNE *+# 4/ 
INC #2>ADDR at the point in the source code where the macro instruction appeared, 
The point is that parameters are allowed, yo MACRO {NC OTHER would be expanded in 
similar way, Dut with values appropriate to the address of OTHER. CBM's .LIB files 
don't work it: quite this way, as there is no scope for varying purameters easily. But 
library saftware is not very different from macra generating software. Consider this 
example, which reverses the low aud high nybbies in the accumulator. 


The code works for any value, and leaves the processor status flags PHP 
unchanged, even where this doesn't matter, so it can be inserted in PHA 
any position where the operation of exchanging nybbles is wanted. ROK A 
The directive .FIL will do this, and provided that the filename is PLA 
reasonably meaningful, the resulting source code should be improved ROR A 
in readability. PRA 
(At first sight, four rotate instructions might be expected to ROR A 
reverse the nybbles, but, since the carry flag is included in tle PLA 
rotation, this is not the case. An cxtra bit would end up between ROR A 
two halves of the original byte. The code (right) gets round this by PHA 
setting the carry flag at each stage to equal the current rightmost ROR A 
dit}. PLA 
ROR A 
18.2 Conversion of machine-language programs between ROMs. PHA 
All PETs/ CBMs ond: VIC are sufficiently. similar for machine-cade ROR A 
interconversion to be likely to succeed. Generally, the later versions PLA 
of BASIC include earlier anes! features as subsets, so upward con- pas 4 


version tends to be fairly easy, while downward conversion may not 
be possible. The steps are as follows: first, the program is disass- 
embled. All jumps and subroutine cails to ROM are likely to be different in other ROMs, 
with the exception of kernel routines. Some of these calls may be made in disguised 
form by pushing bytes on the stack and executing PTS or RTI, and if they are, these 
too must be changed, although as a rule this method is used to jump to tables within 
the routine itself. Zere-page values, and those for the region $200 - $400, may heave 
different functions; this is particularly the case with BASIC 1 as against BASICs 2% 4, 
and egain with VIC, Without an intelligent disassembler to create labels, it can be very 
tedious indeed to convert 2-byte instructions into three bytes. Other difficulties in- 
etude special yalues, for exumple of keyboard decode tables, which vary (sometimes) 
between machines, so that LDA £312 for example is interpreted differently. ROM rout- 
ines may have slightly different effects in their various ROMs. Thus. the ‘print string’ 
routine at CA27/ CALC/ BBID is different in BASIC 4. Chapter 15 has details of all 
PET/CBM ROMs to date, and many standard entry points are listed. Intermediate entry 
points can usually be found with some detective work on disassembled liatinga of the 
relevant parts of each ROM, 

Some interconversion problems are obvievely insoluble: VIC colour programs can’t 
he lmituted on PETs, CRT controller chips can't be progrummed in 86-inch serern mach- 
ines, disk commands sren't evallapie on BASIC 2 Cunlese they're in KAM), an ESCAPE 
key may not exist on tha keyboard, HASIC 1 cannot be used with NMI, In cases of 
thls sort parts of a program will have to bs modified If the original workings ace to be 
retained: otherwisa, silghtly different keyboard instructions and output formats from 
the original will result. It ls impossible to lay down firm rules, since programming 
methods and styles vary, so that while many routines are trivially easy ta convert, 

a twist In the method used makes anuther far more difficult. 

Machine-independent routines (as regards the PET CEM and perhaps VIC, but 
almost certainty noi other machines too} can be written, ar at Jana’ approached, by 
taking advantage of standard feetures. Thus, LOAD is likely to nave ea similar effect 
on all there machines, ao If non-kernet ROM routines wre atored in RAM the rasutting 
code will ha independent of ROM. Same of HASIC 2, for instance, may be traniplunted 
Inta other NAS(ICa, where ita performance will be known, The same applies te some 
caleglation and string routizaa, Apart from tals, kernel routines for input, output, 
testing Stop, and ao on, can odvieusty be used until such time as Ceamodare decides 
to change thla nspect of ROM. It must be said that mony importent axpocts of pro- 
geans are difflcult to mavea betwean machines; 22-, 40-, and 8l-column acreents 
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present, between them, a considerable challenge to the would-be programmer of machine 
independent code. in cases like this, the easiest course may de simply to have several 
programs which run independently; an identifying ROM feature, tested at the start of 
execution, causes the appropriate program of the several co-resident programs to run, 
Alternatively, an approach tess wasteful of space is to collect the divergent parts. of 
the program into subroutines with ROM version tests. 


18,3 Coexistence of machine-code with BASIC: CHRGET, wedges, and utilities. 
14.3.1 The CHRGET routine, BASIC is almost always held in RAM; during execution, 


further RAM pointers are necessary to keep track of the stage reached at every point 
in the run. CHRGET processes one of these pointers, which is the location in RAM of 
the current byte of BASIC. A line like 100 ?"HELLO” is scanned by CHRGET from 
beginning to end, and in each case the accumulator contains a character - the token 
for PRINT, ASCI! for ”, ASCII for H, and so on. (The link addresses and line numb- 
ers are processed differently). This routine is therefore important to BASIC. As we 
shall see, extra BASIC commands can be inserted into BASIC by altering CHRGET. 
It is easy to confuse the operation of CHRGET with the interrupt, as both deal with 
fast-moving events at the core of BASIC. The interrupt is a regular event, which 
occurs absolutely independently of BASIC, while CHRGET ig necessary to process all 
BASIC bytes from start to finish. Thus, extensions to BASIC must use CHRGET, and 
TRACE, if it is to record every line processed, must atso use CHRGET. Any other 
processing for which regular updates are wanted is an interrupt Function, examples 
include repeat keys, cursor flash rate controls, Stop key testing. and music played 
while a normal program runs. 

When the PET/CBM or VIC is turned on, part of the reset routine moves CHR-~ 
GET from ROM to RAM. It is held at EOBS/ EQF9/ D399, and moved by a loop at EOES/ 
E1i2F/ D3C7. For speed of operation, it is 
invariably held in the zero-pnge, at $70 in 





& QO70 INC 77 INCREMENT 2 BYTES 


BASICa 2 and 4, at $C2 in BASIC 1, and at 0072 BNE 0076 
$73 in VIC. The version here (right) is 0074 INC 7a 
that of BASIC 2 or 4. All the versions are B OO76 LDA 0401 ;LOAD FROM RAM 
almilar, but since this is a self-modifying CO79 CMP #9A ;’: 
routine the address incremented at the very 007B BCS OOA? ; BRANCH IF ACC>=#3A 
start of CHRGET varies. ¢ OO7D CMP #20 

Many 6502-based microcomputers with CO7F BEQ 0070 ;SKIP SPACES 
BASIC use an [Identical routine. [t shows D 0081 SEC ;BET CARAY FLAG 
Microsoft's skilful use of the flings as indic- 0082 SBC #30 ; WHEN ACC IS OUT OF 
ators, By (for exampiec) putting characters 0084 SEC ;RANGE #30-#39, 
0-255 into the screen RAM and pointing 0085 S8C #DO ;CLEAM IF #30-239 
($77) at their start, the effects of CHRGET 0087 RTS 


tan be determined empirically, and they are 
summarised in the following table: 


JSR $0070 (labelled A) returns with the accumulator holding the next BASIC byte, 

JSR $0076 (labelled B) returns with the accumulator holding the current BASIC byte. 
Note that the accumulator never returns with a space character, however, —7 
which is always akipped by the loop labelled C. 
Subroutines A and B are sometimes culled ‘CHRGET' and ‘CHRGOT', 

Carry flag, C 

Cleared If the accumulator holds #30- #39, l.e. an ASCIL numeral. (BCC succerds). 

Set If the accumulator holds any other value. (BCS succecds In thia case). 


CHRGET and CHRGOT 


Zero Nag, Z 
Cleared If the accumulator holds any value other than null or colon, (HNE suceenda). 
Set whenever the accumulator holds #0 or HSA, BEQ thug tests for end-of xtutement, 


Negative flag, N and internal overflow flag, V 

There ere not Important, but, for the reeord; 

N ls cleared when A holds #60 - #89, and scat when A holds #BA - éFF. 

V is always clenred, exeept in tha one casa whon A holds #JA (the colon) aid Vo was 
previously xet. 


Summary: (1) CHRGET skips spaces, (6) detecta aumersia auch an inenumbers by 
JAR GOTGs HCC, (co) deteetn the end of a statement Dy JaR OO7N/ aEQ, and {dd} doen Ave 
detnct tukens by seitlig the aogative fig, oe lt might have been expected to dea, 
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14.3.2 Wedges. Extensions to BASIC all use so-called ‘wedges’; this generle name 
sppties to any RAM processing which is triggered via CHRGET. Toolkits, DOS support, 
trace utilities, additional keywords prefixed by !,5,@, and others, all rely on this 
method. Brad Yempieton’s EPROM 'Power' has an automated keyword-defining feature. 
The process is dasically quite simple, but as usual there are plenty of hazards lying 
in wait for the unwary programmer. 

Let's first look at some modifications of CHRGET which are not wedges. 

(1) Deletion of the test for spaces. We can climinate the loop at € on the dia- 
gram from BASIC. If we poke, in sequence, $7E with SEA (this is NOP, no operation), 
$7D with SEA, $80 with $EA, and S7F with $£4, the entire space-skipping loop is 
repiaced by NOPs, The sequence niust be followed: remember that POKE from BASIC 
itself uses CHRGET. so the subroutine must make sense at each intermediate step. 
cup #Z4 always fails, since large values have already been taken out by the branch 
after CaP a3A; and, with 3EQ 0070 preceded by BCS #3a, this branch too always fails. 
So: 





POKE126, 234:POKE125, 234: POKE128, 234: POKE 127, 234 
with BASiCs ? and 4 eliminates the space test. Now, any BASIC including a space will 
give ?syntax error - including the POKEs listed above. This shows how BASIC which 
has been CRUNCHed, or written without spaces, can be run faster than normal, by 
altering CHRGET from machine-code to remove the redundant four bytes. (SEC can 
also be dropped if spc #30 is replaced by SRC #2P). 

(li) Use of the CHRGET in ROM, Even if RAM is changed, the ROM routine 
remains immutable. We can exploit it in a variety of ways. A subroutine call to entry- 
point A will increment ($77), returning an irrelevant value in the accumulator. A call 
to CMP #34 will process the current accumulator contents in GETCHR's normal way, 
clearing C if the accumulator holds a numeral, for example; this is # compact, though 
non-ROM-independent. method for performing such tests, Entry-point D can be called 
from RAM; O0Cb1L JMP ROM-D leaves CHRGET unaffected, apart from taking longer, and 
liberates three zero-page bytes - not RTS, which is still used by a branch. 





Now let's look at some programming considerations relevant to wedges. 

(i) Registers. X and Y are not altered by CHRGET: A, which is loaded with @ 
new value, Is. A wedge routine may need to suve X and/or Y. if these are used in its 
processing. In the case of TRACE, and other extensions to BASIC which are intended 
to feave the program rutining normally, A will also need to be saved, and perhaps PSR. 

(it) Return address. When JSR 0070 oT JSR $0076 is executed from ROM, the 
return address 1S gnved on the stack. Therefore, a wedge with TSx/ LDA O101,x feast 
LDA 0102,% can recover the return address ~ 1, and find where the call was made frorn. 
This is sometimes used (e.g. in DOS support) to exclude some calls, for example those 
in program mode as opposed ta direct mode. if a wedge includes a JSR command, the 
extra return address may need to be popped from the siack, depending on the way 
the subsequent programming is carried out. 

(if) Current BASIC address. The address in ($77) can sometimes be used from 
within s wedge: an obvious example is testing for direct mode, where the high byte 
in $78 is #2, because the buffer extends from $0200 (except in BASIC 1). 

Civ} Positioning n wedge within CHRGET Onty two basie types of wedge are 
possible; those with a IMP or ISH at the Hart of CHRGET, and those with JMP(s) of 
JSR(s) after 0070, These are fixed by ROM. Cutis to J070 and 0078 both occur from 
ROM, so each must be reapected. Moreover, location ($77}, the puinter to BASIC. la 
used In ROM, and therefore cannot ensily be moved; this rulen out 0076 JMP or JSR. 
Any tocation after line 6076 can include & wedge, 0979 JMP ia an obvioun possibility: 
O0dL JMP can be ured, but will onty be entered if the accumulntor holds a value lees 
than #3A, unless 0074 ia changed to 0076 BCS 008! and the routine exits through the 
ROM equivalent of 0979. The two types ure Ulustrated here: 





CHRORT JN WEDGE —~~-WELGE INCREMENT ($77) CHAGET INC 77 WROGE CMP #(H 


RX XK KK Jsh cO76 BHE 0076 BEQ +3 

CHARCOT LDA BASADA CMP acy Inc 78 JMP ROM-CHP «sa 
CMP WBA BEQ +3——~- CHRGOT LDA SASADR PROCESS, .. € 
BCS EXIT JEP 0076 SUP WEDGE Sup 0070 or G07# 
ceP #20 a) PAOCZSS.. .€-- XK XX UE 
BRQ CHRGRT auP 9670 or 0078 RA ER XK 
+. ETC... NEOMR ORK 


Early wedge In CHRGET. Later wadga, after CHRGOT. 
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For the sake of an example, | have written each wedge to test for the GO token. This 
means that GO might be used to trigger ¢ computed GOTO or GOSUB. Other possible 
symbols include any not usually found in BASIC, 1,9, have been used, and other 
possibilities include shift-space, cursor-control characters, and space itself, A whole 
table of processes might follow such » symbol; thus @D 1,3 might plot a point at 1,3, 
where 'D' means 'Draw'; 'C might clear the whole of memory; $D,1 might display a 
disk directory, and each of these commands might be only one of several alternatives, 
The initia? special character makes processing somewhat easier, but isn't necessary, 
and keywords like DUMP or FIND can he checked for and acted upon when found. 

Hoth examples use JMP commands, JSR is often used, and, where applicable, RTS 
can be used, for example in the wedge in the first example. However, if subsequent 
processing doesn't return to the same place, a construction of the type PLA/PLA/JMP 
0070 will be necessary, where the return address is removed, leaving only the return 
address from which CHRGET was called. 


Examples. These three examples illustrate some of the points mentioned, and introduce 
a few refinements which we haven't yet dealt with: 


(i) Use of t from BASIC to reverse the screen. This js straightforward; one of 
the routines in Chapter 9 can be inserted to perform the reversal. First, enter the 
routine (right} which processes the wedge. : 
Then enter the subsidiary machine-code t 
modify CHRGET, and run it. If this is done 
first, BASIC will erash. producing effects 
similar to those which occur when the {RQ 
vector is changed to some non-existent 
subroutine. 

Note that the wedge processing has 
a test for direct-mode; if this is in force 





0300 CHP #21 

Q302 BEQ O307 ;BRANCH IP ! IN ACC'R 
0304 JWP EOSE/ E102/ D3A2;BASICS 1,2,4 
Q307 LDA 78 

0309 CMP #02 

0308 BEQ ZXIT ;BRANCH IF DIRECT MODE 
30D TYA 


_Q30E PHA SAVE ¥ ON STACK 


the ‘command’ is ignored. The object of O30F --REVERSE SCREEN USING A & Y-~- 
this is to prevent unwanted direct -mode PLA : 

screen reversals. This, of course, hardly TAY ;RECOVER ¥ 

matters, Dut it might be important in EXIT JMP 0070 ;NEXT BASIC INSTRUCTION 


other cases. Conversely, only direct-made 
might be required, as it is in the DOS support programs. Now, 


M0079 OO79 

.f 4C OG OF xx wx AK KE 24 
converts CHRGET to its new form (right). 0070 IRC 77 
LDA #4C/ STA 70/ ete can of course also 0072 BNE 0076 
be used. (BASIC 1 has different addresses), 0074 INC 78 
The mechanism by which the wedge operates 0076 LDA BASADR 
should, i hope, be clear. Usually, CHRGET oo79 «Jap Q300 


won't find 1, and following the rautine from 
the start on this assumption shows that the operation of CHRGET is exactly ng normal, 
except for a smail slowing caused by the extra code. 


(ft) TRACE. The version in Chapter 5 Inserts a wedge at entry-peint D, of the 
form JMP WEDGY where the wedge ia high in RAM. The code then follows the sequence 
STA/ STK/ STY/ LIST LINE, WHERZ NECESSARY/ LDA/ LDX/ LDY / JMP FOC6 or ELOA or RIAA. 
Thene latter alternatives apply to BASICs 1,2, and 4, and are the ROM entry-points 
which correspond to 2. In thia way, CHRGET is left fundamentally unaltered, but 
Processing tekes place using parameters (e.g. current IInenumber) of BASIC. This isu 
Hyhily risky rowtine fas use with TRACE, because entry-point D enn only be renched 
If the BASIC byte is in the range #0 - #$39. The warlge is therefore often byperised, 
In practice, all BASIC Him Inetude an end of Une null charaeter and/or ASCO sumer 
ala int GOTO, and the added verscrtifty given by a wedge which can Inave uthers in 
place to run normally ts an advantage. 


(IL) Computed GOTO une GOSUH, The fayvourud form of wedge in the reptnace- 
ent of 070 INC 77 by JMR WROGE | whore the address WEDGE Ua typlenily in bhgh 
HAM or ln EPROM. Cntlike wedges lower down in CHMGET, this asaures pelority of 
Whatever new eading Is fe he gotradured, Phe lewd: fa wlightly different from the 
previous examples, Deciuse the wedge replaces GETCHR rather Chute GOTCUR, In athe 
words, wodge praceadieg hare must include Incrementing Une contents of C87), 


a. 
etter a ee 


oem a FA IR AEE REN Lo ak, EL EE tL  ~. oaerg  r m mN a ET 


— 
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An elegant way to do this is to use the three bytes after IMP. A aubroutine to incre- 
ment ($77)'s contents can be put here, so JSR 0073 functions exactly like CHRGET, The 
subroutine can be INC77/ BNE +3/ INC 78 or, what ia perhaps slightly easier, the ROM 
routine. The revised CHRGET routine and its wedge has this structure: 


OO70 IMP WEDGE WEDGE JSR 0073 ;LOAD A WITH NEAT BASIC CHH., 
0073 JSR KOBS/E0¥9/0399 ;SET STATUS FLAGS, AS GETCHA 
0076 LDA BASADE etc. .., Perform processing; return either 
+. unchanged... with JMP 0076 or with RTS, if A and 
atatus flags are correctly aec. 


The following example is a computed GOTO using the GO token; it is written for BASIC 2 
but easily modified to BASIC 4. There is a shorter, but less easy to understand, version 
oy B Templeton [in BASIC 2: JSHCC8B/ JSR D6ED2/ JSR C7BO/ MMP 0076] which reappears 
in the GOSUB routine below. apart from the additional stack manipulations. {t is poss- 
Dble to combine computed GOTOs and GOSUBs in the same wedge, using this. 


0070 JMP 0300 0300 JSR 0073 ;GETCHR. NEXT BASIC BYTZ IN A 
0073 JaR ZOFS 0303 CMP #CB 518 IT A 'GO" TOKEN? 
0076 ...unchanged... 0390S BNE 0321 ;NO. EXIT TO RESET STATUS FLAGS 
0307 JSR EOFS ;YES: INC POINTER TO NEXT BYTE, 
Md 0070) 4600008 520 E 2 ROMA AEE 030A JSR CC9F ;INPUT AND EVALUATE EXPRESSION, 
With this wedge in place, try this: 30D JSR DGD2 ;CONVEAT FPACC#1 [NTO INTEGER, 
an. 0310 JSR CS$2C ;SEAACH FOR LINENUMAER IN ($12), 
eee, hae ii 0313 BCC 0324 ;CARRY CLEAR IF LINE NOT FOUND; 
a ‘ea ttr: Daes aa Cook 0315 LDA SC ;{$5C) POINTS TO LINK ADDRESS, 
20 PRINT "4": END. 0317 ADC #03 :SO ADD #4 [CARRY IS SET} 
: O39 STA 77  ;AND PUT RESULT IN ($77). 


which prints | to 4 during execution, 031B LDA 5D 

Some odd anomalies tend to occur with 031D ADC #00 

wedges unless there is specific pro- O31F STA 7a 

tection within them against direct-mode 0321 JMP 0076 ,;CONTINUE BASIC 

entry and entry from the input buffer, 0324 JMP C7ES ;'UNDEF'D STATEMENT ERROR’ 

if either of these !s omitted, entering 

programs when the wedge is enabled may give oddities. Lines like 100 :t may be nec~ 

easary. The DOS support ('Universai Wedge’) is instructive in this respect. Another 

type of anomaly is the dDehaviour of conditional statements; {f X=1 THEN @123 , a typ~ 

ical wedge, may a/woys execute, irrespective of the value of X, unless rewritten in 

the form {IF X=s1 THEN: 9123. 0300 JSR 0073 ;GET NEXT CHARACTER 
Since the wedge is processed before CHRGET 0303 CMP #8D ;GOSUB TOKEN? 

is able to pass lta results ta ROM, ordinary tokens 0305 BNE 0337 ;1P NOT, EXIT. 

can be altered: #$89 (‘GOTO') can itneif be mod- 0307 PLA ;RECOVER RETURN 

ified, for instance. Computed GOSUNA (rigtt) is , 0308 STA 033A ; ADDRESS AND 

more complex than GOTO, On disnasembling GOSUB 030B PLA ; STORE IT. 

in ROM, one finds a fot of stack activity folluwed 030C STA O33B 

by GOTO. KETURN unruvele the stack information. QJOF LDA #03 

It is important with a wedge to save the return 0312) JSA CIJ1B ;CHECK STACK DEPTH 

address of GETCHR (which Is called by GETCHR‘a 0114 LDA 78 


final RTS), fur use by the exh JMP 0076 from the O31¢ PHA 
wadge, tn the example it is atered in RAM. 0317 LDA 77 
Subroutines can be called by name, rather 0319 PHA 
than linenumber. If a dato-provessing aubroutine, GI1A LDA 37 
any, startw at L0000 and DA-10000. then GOSUB OJ1C PHA 
DATE Is usable. Such names must contuin no res~ 6410 LDA 34 
ervod BASIC worda, of course, sad their yvatues Our PHA 
must ba correct, They will nut, for cxumple, in 0320 LDA #4D 
Renera) surviva renumbering correctly. 0522 PHA 
‘The use of location $400 in those examples 0324 JR FORO ; INCREMENT (77) 


hon no particular significance and in for conveniences: O3a8 JSR CCAR; EVALUATE EXPRENB ION 
only, Note that all wedges Inevitably have a slowing 9399 JNK DON {CONVERT TO a-BYTEA 
effect on BASIC, #o a routing to ‘RHE the wertge 0220 JSA C7BL ; UPDATE (77) ADURESS 
when $'s not In ura may be worth ineludiuig ia the  osaF LDA 0340 ; REPLACE RETURN 
overall program. Ajso, of course, a routhne lo tice O32 PHA ; ABDREAS FOR NTS 


It on in convenjent; SYS 40960 or SYS 45050 0333 LDA 0334 ; ON STACK 
haa thls function In many hurdware add: ons, O38 PIA 
OJ3t SMP OO76 ,LUNTINGUE 
DERE 52 HYTES BTORAGE 


. 


HAE CAINE REST SO AT ACR TSE RLARATS “COUTNS CAMINO ap arg 


| 


ee 
Ae Seams a a gE ERM NEA a RE NA om 
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18.3.3 BASIC utilities. Chapter $ has a number of examples of machine-code pro- 
grams which process BASIC. Two examples here exemplify suitable methods for dealing 
with this type of problem. 





(i} Search and replace. A feirly simple routine for any BASIC, which changes 
single characters, follows, It can exchange all occurrences of PRINT to PRINT#, or of 
PEEK to USR, for example; or, within quotes, al! shift-spaces may be converted into 


spaces, or all cursor-downs into (say} reverse charactera. The logic is shown in the 


flowchart. Note (a) how the end-of-line 
START 





test is necessary to prevent link addresses 
and linenumbers being wrongly changed, 
(b) how the end-of-program is tested, 
(ce) the use of the quotes flag to show 
whether or not some particular region of 
BASIC is within quotes, and therefore 
may require special treatment. 

The routine uses addresses $0 - $2 
in the zero-page, but no other RAM apart 
from its own (relocatable) code, 


Bet pointer=$0404 


Quotes flag off 





SOO=QUOTES FLAG {#0 GFF, #FF QN) 
SOL=POINTER {LOW BYTE) 
SOZ=POINTER (HIGH BYTE) 


Increment pointer 


and load character 


0300 A2 O00 BS GO AO O1 AD O04 
0308 85 O1 85 O2 £6 OL DA 02 Yea 
0310 EG 02 Al O01 FO ta C9 22 

6318 DO O8 48 AS 00 49 FF BS 

0320 00 48 £4 oofno £6)c3 (99) No 

0328 DO £2 A9(S}81 OL DO DO Quote? 
0330 Bl O1 CA 11 O1 FG LL 38 [CHRS$(34}} 
0338 18 86 00 Ad 05 65 01 35 
0340 02 BA 6S 02 85 O2 DO CA 
O348 GO xx xx 2K KE XK XX XX 


@99) (' PRINT‘) [S CHANGED TO 
(805) ('PRINT#') IN THIS EXAMPLE. 


(DI-EG: IGNORE CONTENTS OF QUOTES. 
@@ £6) CHANGE ONLY QUOTE CONTENTS, 
CEA"¢Q: CHANGE BOTH, ON SYS 768 
N.B.:The quate character itself 
cannot be changed ueing this 
Toutine aa it stands. 














Next two 


bytes null? —_ 


No 






Reverse the 
quotes flag 


Ef 
io 






Is quotes 
flag on? 










Byte gatch 
with sought 
character?, 


(li) Hashtotal, A BASIC or 
machine-code hashictal is often 
helpful in checkiny whether load 
errors may have occurred or 
whether the currect version of a 
Program hay been loaded. We need 
4 routine to combine ea:h byte 
from the start te the end in a 
repeatable way. The example 
Program (next pape) cremled a 
Kingle ‘byte hashtetal, by vxctua 
Ivo: ORing every byte from (428) to ($24) and printing the result. Tila value could 
be atorced in RAM ang cheeked aulomatically by the progrnat iteelf, The routine uses no 
Zero-payy poloterk, but fantend ia self-modifying. The bashtetelling process stops when 
tila modified actdeesa equates Che oad oof prugena pointer in ($2A). Obviously. other 
gery paye start and end ponders eno be substituted, such as ($7A} for WASHC t ur 
C820) for VIC, The print routine (this prints finemuiunapers, and cana be tracked dawn 
al the end of RESET, where tt peints the number of bytes free} differa between KOM, 
Chave used $YS 700 beeuuse Ue foentlua da enay te remember, at lesat in dechnal. The 
Peutine neods uix address changes Uf it is ta ba reiocatad. 





Flowchart: replace only characters outside quotes. 


eet 








Programming the PET/C8M + 370- 14; Effective 6502 programming 


O2BC LDA 28 ;STORE STAART-OF-PROGRAM POINTER IN RAM ADDRESS 
O2BE STA O2C9 
02c1 LDA 29 
a203 STA 02CA 
O3C& PHA 
LOOP O2CT PLA ; EXCLUSIVE-OR POUNTER CONTENTS WITH HASHTOTAL SO FAR 
O2ca EOR xxxx 7 
O2cBh PHA 
O2CC INC 0209 ; INCREMENT POINTER 
Q2CPF SNE O2D4 
ODL ENC O2ZCA 
0204 SEL :COMPARE POINTER WITH END-OF-BASIC. BRANCH TO LOO? WHILE LESS 
0205 LDA Oo2c9 
02D8 SBC 2A 
G2DA LDA 020A 
O2zbD SBC 28 
O2DF BCC 02C7 
O2EL PLA ;RECOVER HASHTOTAL (STORED ON STACK AS SBC USES ACCUMULATOR} 
Q2E2 TAX 
02E3 LDA #00 
O2E5 JWP DCgF/ DCO9/ CFS3; PRINT 256*A + X, WHICH NOW = HASHTOTAL 


14.4 Kiachine-code loaders in BASIC: ordinary loaders and relocating loaders. 


14,4,1 Ordinary loaders, When machine-code is to be stored in some fixed place in 
- notably the cassette buffer(s), which, except for buffer#2 in BASIC 4 disk 

operations, are only used by BASIC during tape input/ cutput - a simple series 
of pokes provides an easy way to load the individual bytes. Section 4.1.9 has a BASIC 
routine which uses the keyboard buffer and screen together to convert consecutive 
bytes into decimal BASIC values, for later poking back into RAM. It may be easier and 
jess space-consuming to use hexadecimal strings; the two subroutines below are comp- 
tementary, the first generating strings like thot in line 9 of the second program, which 
in turn, given o starting address, reconstitutes the code in RAM. 

MITIM MITTIN LULL 

$1492 REM ## ROUTINE WHICH STORES MACHINE CODE FROM KAM INTO A BASIC STRING. #8 

$1493 REM ## ** SEZ THE FOLLOWING ROUTINE FOR TYTICAL PROGRAM TO RECONSTRUCT #7? 


61494 REM OF ** THE CONTENTS OF RAM FROM WITHIN ANOTHER BASIC PROGRAM. ‘f 
one REM OHPSFHRTIEOR ORO TEOEEE ATOR DOSED EEE E RESO EEELOAE CATA DEL EEREETETUTTUASEE 
96 REM 


61500 INPUT " RAM START LOCATLON";S 
6t510 INPUT * RAM END LOCATLON";E 
6L5t5 LNPUT “STARTING LINENUMBER";L 
61520 PHINT "(CLEAR)" ;HIDS(STRS(L},2) ;"MCS=HCS+" 5CHRS (34) ; :GwPEEK(54)+256"PEEK(55) 
61530 POR J = S$ TOE 
61540 Bs POS (0) + PEEK(196)>74 THEN PRINT FHR$ (34) 3° [HOME] [DOWN] [DOWN] L=" {Ls "+1258"; 5778 
3Bs"sGOTO";G 
61550 IF POS(O)+PELK(196)>74THEN POKE623, 19: POKE624, 13: POKRG25, 13: POKELSB, 3: 2ND 
$1560 P=PEEK(S):Q%=P/16:PeP—)2*16:REM QZ 1S HIGH BYTZ, P LOW BYTE, IN DPCIMAL. 
green C=P:COSUS $1600: CRQz:CUSUB G1600:REM Q%29 THEN Q7<QX+16: PRINTCHAS (G2); 
NEAT 
eet PRINT CHR9(34): POKE 623,19: POKE624,13: POKEL58,2: END: REM LAST LINE 
C REM 
62599 REM ** CONVERT OEC(MAL FROM 0-15 INTO HEX FROM 0-9, A-F AND PRINT DICIT 4## 
61600 C = C + 48: IF C > S? THEN C = C47 
61616 PRINT CHRS{C); 
$1620 RETURN 


A aN aaa EXAMPLE ONLY 

RPM 

HELGE REM POPPER EPEAS OER EET ATR RAR Z AAO OORT E ER OREOESRETTSE TREES EERSTE EET R TEES 

OL747 REM ## TYPICAL @HOCKAM TO CONVENT A BASIC HEX STRING BACK [NTO MEMORY #F 

hae pi PIPADERCAR AEST OEE CER ERA AREAL EAE OOT ADEE ERAGE TCE EE EEEI EERE 
Fx 

61750 INS UT "START LOCATION OF CUBE"; S 

6/760 FoR J = 1 TO LAM (HOS) STEP 2 

6L770 Qk = ASCE MINT(MCS,I,L) > ¢ REM ASCIT VALUE OF HICH AYTH 

61780 P = ASC( MIUSCMCS,J+1,1) Js REM ASCLL VALUE OF Low BYTE 

61790 QE Qk ~ ASC{"O")1 QR = Qk % 78 (Q%99) 1 KEN DECIMAL VALINE OF HICH BYTE 

6ES00 P = P + ASC("O"}1 PrP + 7* (p>9) 1 RPM DRCIMAL VALUE OF LOW BYTE 

ALALO POKR § + J/2, 16 * QI +P 1 REM NOW PORE IM TRUE VALUE 

61A20 NEXT 

61890 ENG 
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14.4.2 Relocating loaders. Machine-code which works correctly in any part of memory 
{subject to constraints imposed by the other software and hardware) is called relocet- 
eble, Code of this sort can be put into RAM by a straightforward set of pokes, with 

a variable starting-point from which the bytes ere written. This can't be done, without 
modifications, with most code using absolute addresses. A relocating loader pokes in 
eode, correcting the relevant bytes. As an example of its use, consider BASIC using 
several routines in high RAM; a relocating loader can painlessly put (say) several 
different keyboard redefinitions there, all fitting tidity into the space, and all working 
correctly. In the same way, a loader can put in its code into machines of differing RAM 
capacity. Relocating code may also be machine-independent, but this is more difficult. 

Which inatructions relocate? All implied mode and immediate mode instructions, 
all branches, and all accumulator made instructions relocate, For example. TSX, RTS. 
CLC, and LDX #00, LDA #FF, and BEQ +6 and ROL A can be poked in byte form any- 
where in memory without affecting their disassembled equivalent in any way. The prob- 
lems arise with addresses. With BASIC, zero-page instructions can usually be consid- 
ered to relocate, because their functions are fixed, and an instruction like LDA ($2A),¥ 
has to be retained wherever the code is. ROM addresses are fixed too. Addresses 
which have to be varied look like this: 7000 JSR 70K4/ LDA 7OBO,K/ CMP 7100/ IMP 7050 
and so on, which after relocation becomes 6090 JSR 6G£4/ LDA 60B0,X / etc. 

Many approaches are possible to writing such code: here, I'll assume the code is 
to be put into the tep of RAM, and is to be louded in decimal from BASIC. The well- 
known use of negative numbers as distinguishing marks is used; machine-code versions 
can't do this, and may use zero bytes instead, followed by a routine enabling a check 
for real zeroes a8 opposed to code zeroes. Supermon 4 (q.v. - appendices) has an 
example. 

We can use the following loader, which may be embellished in various ways, typ- 
cally to print out initialisation addresses, special locations, and instructions. The 
Peeked values apply to BASIC >1; others may be substituted: 


100 T=PEEK (32)+256*PEEK (53) ;REM TOP OF MEMORY FOR SASIC 24 4 
110 L=T-N :REM N=NUMBBR OF BYTES OF CODE; L=LOWERED MEM.TOP 
1270 POR J=L TO T-1: READ If :REM DATA HELD IN (SAY) LINES 0 AND FOLLOWING 


430 IF XEcO THEN Y=Xq+T: [nV /256: Za¥-XG°756; POKE 3,2: J=kel ¢: 

:BEM ¥ IS RELOCATED VALUE CALCULATED FROM WEG.XE 
140 POKE J,23%: NEIT 7REM COMPLETE PROCESS FOR ALL VALUES 
150 PORE 52,L-INT(L/256)*256: POKE 53,/256: CLR:REM RESET TOP-OF-MEMORY 


To convert code into data which this program can use, follow these steps: 

(i) Enter the code into RAM (and preferably test It). 

(i) Print (or write out) the disassembled veraion. A digassembler giving decimal 
values of locationa ia helpful. 

(10) Mark all the absolute addressea which need changing during retocation. 

(iv) Replace euch of them by its offset from the end of the program: i.e. count 
from the end of program plus one backwards, the result belng a negative number from 
-1 ta -30000 or so. See the example; thls fs easier than it might seem. 

{v) Convert the bytes into data statements and enter them, Note that each new 
Negative value replaces two bytes ag a rule. 

(vl} Enter the vatue of N in tine 110. 

(vii) Test the loader: run it several times, and check that each routine is in- 
depent and correctly set up. 


Example. The nonsense program (right) has @ $2126 2 027A san (oa7e ) 
Subroutine call, a table of byte values, and a 96 027D RTH 

branch. The branch, because of Its relative 162¢«2 Moar LDX #2 
Addrensing mode, relocates; so doea the table, 221 134 0280 «CMP{O4H6) X 
sid the single byte, Implicd-moda inatructions 203 0283 DEX 

and the Immedlate-mode instruction. So the 208 250 0244 BNE 0280 

Only addresses to be relocated are those clreled. on -§) 0246 RTS 

Counting back from the end, we flad that 45 46 Q787 «=. BYTE $41, $4] 


6272 fa tho 1ith byte, and 0288 the third; no -1i2 
and -3 reapectively repiace all occucrencea cf these two addreases. The DATA stato- 
ment is therefore 


O DATA 32,-11,06,162,2,221,-3,202, 208, 250, 94,68, 66 
and the number of bytes in the program is 15, so line 110 becomes 
116 LeT-ib . 


So ee nn ae-iz ait tec iimeniaied( shins bemca  Aaiammeate i dachemereeteiteediatenn tc eeieaniiaminatae ee 
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Our loader should now be capabie of piacing 3ac4a JSR 3BC8 
ita code into memory as the diagram (right) 3BC7 RTS 
shows, with adjacent versions of the routine 38CB LDX #02 
abutting exactly. Another temporary line of SBCA CMP 3BD0,X 
BASIC: maACD DEX 

143 PRINT "TOP" T "TO" L 3BCR BNE SBCA 

-3SD0 RTS. 


wilf show the continual diminution of RAM 
as the routines accumulate in the top of 
RAM. 


38D1 EOR (42,K) 
3803 JSR 3BD7 


Refinements on this process include: 
(i) Test for type of ROM, perhaps with a 
few pokes to modify ROM addresses, 


3BD7 LDX #02 
3AaDS CMP SBDOF,X 


(ii) Test for size of memory, which may be 30 DEX 
too small, 3BDD BNE 3AD9 
3B0P ATS 


(iii) Automation of some of these processes, 
inctuding calculation of negative values and 
of nuuber of bytes in the program, 


3BEO OR (42,1) 
3Ba2 JSR 3BE6 


(iv) Inclusion of the memory-lowering pokes ea ae 02 
into the initialisation routine itself. In this aca ao. on 


way, a pre-refocated machine-code program 
ean be loaded as a file, and when initialised, 
will set the memory-pointers so that it cannot be overwritten by BASIC strings. 


14.5 Pure machine-code techniques. 


'Mand assembly! This is the name usually given to a hybrid technique for machine- 
code programming, in which the final code is not fitted together as a solid chunk in 
the manner of an assembler, but insteed is distributed in RAM in a way convenient to 
the programmer, in separate subroutines. For example, a disk-processing program 
may start at $3000 and have 50 or so lines of program terminating with a message to 
be printed on successful completion. Major subroutines, to read, write, compare, move 
data, and so on, could be at $3100, $3200, $3300, and other addresses in this series. 
Provided that the documentation keeps a record of the function of each subroutine, 
code built up in this way is fairly easy to check (subroutines can be tested individ- 
ually) and quite easy to modify, without having to reassemble the entire program. 
Moreover, skeletat trial programa can be written and run, and later elaborated upon 
nnd made user-friendly by expanding parts of the code as required. The sequence of 
the parte ia not changed by this process, as it may be when assembler programs are 
patched. Different depths of subroutines can be represented by thelr locations: as # 
COBOL program might have controlling modules prefixed by A-, their subsidiary 
routines prefixed by C-, and their elementary commands to read or write single rec~ 
ords prefixed by E-, sa $3000 f{ may contain the highest-level control programs, 
$4000 (f their subroutines, and $5000 ff the elementary subroutines. Since enormous 
machine-code programs are rare, there ia not often a shortage of RAM for the purpose. 
There is of course no renson why this procedure shouldn't be carried out with an aas~ 
embler; all that's needed is a fair sprinkllng of commands Iike *«3000 and *=3100. In- 
evitably, JMP or JSR commands (or stack pushos with RTS or RTI) have to be used to 
communicate between routines; branches cannot reach far enough. (Thia qualification 
ia removed with the 6809 chip, which not only has ‘iong branches’ but ‘branch saving 
return addresa'. Theso features make 6809 code much more easily relocatable than 
6502 code}. 


Running with SYS. LOAD assumes BASIC; RUN ia expected, the CIM having no 
command to run pure machine-code. [f wo have a machine -code program, how can we 
wrile [tf so that RUN executes It? The answer {8 to put ina S¥S call to the code, To 
wo how this can be done In the goncrul case, let's suppose we have 4 routine starting 
at $3000, RUN executes a program from [ts starting-point: we therefore precede the 
machine-code with « BASIC program. The cuulust woy to dy tis is to insert bytes Iike 
these; z ' 

ACTUAL BYTES: 00 0C 04 GO 00 YE 31 32 32 38 38 00 00 
BABIC EQUIVALENT: MH Line Linet 8¥YS 1 2 2 @ AW Wg 


where @ denotes the null byte. Tho link addroass (>$040C hera) points to the firat of 
tha two end-of-program marker byten, on ihe assumption that $0400 Is the addrena of 
the start of thia machine-code, The Ilnk addroas cannot ba soro. The arrow marka 


EE EE a TEE PNT NO NTS ITE FN TOIL SATAN LED ECT I SR cope atin . 
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the start of BASIC, as determined by the pointers in ($28) in BASICs >1, and {$7A) 
in BASIC i. Unfortunately, the byte previous to this must be a null byte, imitating an 
end-of-line, and this usually only happens with the standard loading and saving pro- 
cedure where 50400 holds #0. So entry of 


0400 00 OC 04 OO OO 9E 31 32::SYS 12288 ts assumed here, hut obviously other 
.0408 32 38 38 00 00 OO xx xx; values, from SYS1039 up, are possible. 


O028 OL 04 xx xe xx Mx XX KX ;Top of memory underlined; muat > $3000, @.g.FF 32. 


fdllowed by SAVE will convert the machine-code into a pseudo- BASIC program, which 
can be RUN. In this case, all the bytes from $0410 to $3000 are wasted; to prevent 
this the code could be relocated down, or another loader used to put @ zero byte in 
the position corresponding to $0400, boring though this may be. 

It is not strictly necessary to include three null bytes after the BASIC SYS and 
END program, but it tidies LIST. 


and 


18.6 Debugging machine-code. 

This list, which is naturally not exhaustive, includes many errors which experience 
shows to be common in 6302 programming. Errors in the design itself are best cured 
at the earliest stages; careful analysis and dry-running of code with both typical and 
abnormal data should ensure that a program is fundamentally sound. 


Simple errors of carelessness. These may remain undetected far a long time in mach- 
cade, because no ?syntax error warning ever appears. Examples include: 
(i) Transcription errors. Typically 7038 for 703B. 
(ii) Omission, or inclusion, of immediate-mode #, as in LDA #QL/ PHA/ LDA 02/ PRA. 
(iil) Use of wrong ROM addresses, for example FFE4 as output, or, with ROM 
addresses not in the kernel, those for a different ROM from that in use, 
(iv) Branch errors are quite likely to occur in code not written by assembler. 


Addressing mode errors include 

(i) Confusion of order of low and high bytes of an address. 

Gi) Failure to understand the method of working of indirect addressing. 

(iii) The attempt to use indexed zcro-page addressing ta extand above SFF. 
LDA $AB,X wraps around back to zero it X exceeds #54, 

(iv) Other indexing errors, for example: LDA 0102,X/ STA 0100,¥/ DEX/ DEY/ 
BQ -1¢ loads garbage if X drops to #FF and below, which is untested. 

(v) Program design may oe weakened through failure to appreciate limitations of 
the chip; e.g. tripling A by TAX/ ASL A/ ADC X is impossible. 

{vi} Indirect jump has a bug: JMP (03FF) tekes its address from G3FF and 0360. 


Calculation errors involve addition, subtraction, and negation, for example: 

(i) It's eaay to forget that only the accumulator is holding the result. 
LDA #2/ ADC 1234 adds 2, but the contents of 1224 are unchanged. To 
change 1234, 9sTa1z34 is necessary. 

(i) The carry bit may give problems: the rule is usually to clear lt before add- 
Itlona, and set It before subtractions. 

Gii) A 2's complement is always 256 minus the original byte, or 65536 minua a 
16-bit integer, and so on, This is EOR #FF ¢ #1. 


Errors with status flags. There ia a lugic behind the setting of flags, but It ts not 
easy to get used to it. This cxumple: LOA AB/ CMF #07/ BEG #1/ RTS/ STA O08 
stores @ zero value in 08, but this does nol set the zero flag, atthough londIing 
the value from 03 does set the Mag. Other problems Include the negntive flag 
with CMP, and the fost that incrementing a value from 127 decimal ta 128 makea 
the value change Prom ‘pouilive! to 'negnutive’. 


Stack errors: the rule Is to have the some number of stack pusher and pully if a sub 
rovting Is to retuen Jn the normal way. tf a subroutine stack $6 pulled before 
belng pushed, it ia Important to return the correct valuea on the slack before 
RTS unless apeciss processing is being performed. 


Errors In which & program ts modified finclude programs partially overwritien by BAS: 
IC, or by cassette activily. ar by BASIC 4 in enagetio buffer #2, or by the pro- 
grem iieelf. 2 hyte pointers may ve updated while they are til dn uee, so that 
they temparnrily pulst leon wrong aren of memory. Often, AVX, or Y is changed by 
n subroutine op interrupt. and haw ta be xaved In RAM ov oa the Kiack , 
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14.7 TEEE-988, VIA, and PIA: interfaces to the outside world 


The (€EE bus {General Purpose Interface Bus). This standard 'bus'. permitting 
interchange of data between devices, is described in the IEEE document IEEE-438, 
published in 1978 and itseif based on a 1975 standard. Any devices, subject to 
certain imitations, become plug-compatible, and able to transmit and reecive ASCIF 
data, Why should this be a problem? ln the first place, innumerabie variations 
are possible in the signals controlling the data flow. A standard set of commands 
indicating which lines are to be active and when is needed. Sacondly, if all the 
devices were timed by some central clock. date could be passed without problems 
of synchronization between the devices: the same order of magnitude as obtains 
within RAM could apply to data transmission rates, But independent pieces of 
equipment are not synchronized, and a fairly elaborate system of checking is used 
to determine when data is to be sent. This process is called ‘handshaking’. The 
two-way capability of the bus makes for complication. [EEE equipment tends to 
be costly. Moreover (this happens in many computer-related fields) large chunks 
of the standard may remain unused. The IEEE standard's design parameters were 
apparently based on the characteristics of equipment already in use, and this 
design approach has obvioug risks. 


Description of the bus. The IEEE-468 bus is a cable of 16 wires, 8 wires carry data, 
usually in ASC farm with bit 7 used as a parity check. The data lines transmit 
one bit each, so that an &-bit byte is sent as a unit; the result is sometimes 
described ‘bit perailel, byte serial’. Handshaking is carried out between each 
byte. Not surprisingly, this slows the rate of transmission, which in any case will 
be slow if one or more of the receiving devices provesses its data ata relstively 
leisurely pace. 1 megabyte per second is the maximum allowed by the design; CHM 
equipment has a maximum of about 5000 bytes per second. 3 of the remaining 8 
wires control the handshake. The CBM’s ROM from $F000 upwards includes its 
{FEE processing, in addition to tape and monitor programs. A fair proportion of 
its IEEE work is concerned, as we shall sec, with setting these handshaking lines 
and generating error messages and ST (status flug) values if the returning signala 
don't behave in the correct handshaking manner, Finally, 5 wires are concerned 
with bus management. Only 24 of these are used in the PET/CAM. This is caused 
by Commodore's design system, in which the computer gets priority over all other 
devices on the bus. There are quite severe restrictions on cable length between 
pleces of equipment: not more than 5 metres between devices, and not more than 
20 metres overall, are the figures usually quoted. For this reason, VIC has a 
tlifferent connector, Dased on the k$232, whieh has a much better linelength. The 
RS232 (for example) can operate with two wires only. However, since interface 
boxes are available, this makes no great difference, except that the price of the 
total equipment package ia raised. The advantage of the IEEK omerges when 
electronic and scientific equipment of a technical type (i.e. not printers) ecquires 
control by a CHM computer. Before describing the programming of this dus, we'll 
look at the [EEE port as it appears on all PET/CBM machines. The meaning of 
the mnerionics will {I hope) become iess obscure as we proceed, The early manuals 
for the computers, for example part no. 320856-3, contain hardware data on the 
pin connections, their hardware addresses, handshaking and the management bus, 
ST, and a much-reproduced table of [KEE commands, There's also sume account 

of CMO, GET#, INPUT#, and PRINT#, which of course are oll HASIC's way of 
moving data on the bua. 

The (EEE port, The [EEE port ia in the middle of the back of the PET/CBM, 
lis pins, and the corresponding JERE conacctor an it appears(aay) with a disk unit. 
lubellcd with REE mnemonica, are arranjed Ike thla:- 
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IEEE mnemonics and concepts. Ag we have seen, there are three conceptually 
Separate sets of wires or lines in the [EEE tus. These are called Data Lines, 

Data Byte Transfer Control Lines (for neandshaking!) and Genera! Interface 
Management Lines (which the controller uses). Each of the 16 lines hes 4 mnemonic. 


DATA LINES 
DIO1 ~ DIO8 are 8 dats Lincs (‘Duta input/output') which carry single 
bytes of data and of commands. 
DATA BYTE TRANSFER CONTROL BUS 


DAV (Data valid‘). Tells listener that new data is on the bus. 
NDAC ('Not data accepted’) Tells talker data hasn't been read yet. 
NRED (‘Not ready for data') Telis talker not to talk yet. 


GENERAL INTERFACE MANAGEMENT BUS 








ATN (‘Attention’) Distinguishes commands to devices from data. 

EO] (‘End or Identify’) Indicates that the current byte is the last. 

IFC (‘Interface Clear'} Clears all devices on switchon or reset. 

REN (‘Remote Enable') Gives control to other device (not used with CBM). 
SRQ (‘Service Kequest') AHows a device to request service (not on CBM). 


All devices on the bus are controlled, at any given time, by a single ‘controller’. The 
other devices may be ‘talkers’ or ‘listeners’, A ‘talker’ transmits only; some technical 
measuring devices are of this type. A ‘listener‘ receives data only; many printers 
and plotters illustrate this. Another type, the 'ttiker/listener', as you will not be 
surprised to real. can perform both activities; Commodore disk drives and modems 
illustrate this. The bus may be arranged with devices in a ‘star’ pattern or 'daisy~ 
cnained' together, or a combination of these; it doesn't matter to the bus. These 
devices may be any mixture of talkers and listeners. Much of the time the devices 

May be inuctive or switched off. A ‘talker’ doesn't have to talk all the time. 


The next important concept to grasp is the active jow principle which the IEEE 
uses, Unlike all the remaining operations of the CBM, on the IEEE 'true' is low, 
{0), and ‘false’ is high (1). This applies to data and commands. In machine code, 
therefore, data is EORed with 4$FF before transmission. With the CBM, the output 
register is $£322, so EOR #$FF /STA $E822 precedes datu transmission. Another 
example (ece next page) is the values assigned to the IEEE locations when the CBM 
is ruset or powered on; each bit which is configured for output by the initialisation 
aystem is set high, rather than the alternative convention of the low value. This 
Convention is determined by hardware considerations. Any one device can hold a 
line in the low state by keeping the line impedance high, irruspective of other 
devices’ states, and this is useful when assorted devices with a range of response 
times hove been connected to the same bus system. The ‘active low’ principle is 
responsible for the double negalives which tend to be a confusing part of discussion 
Sbout this bus, particularly when it concerns the control bus connaands which use 
Ines which wait to be releused by sll the devices. For example, a device listening 
On the bus and ready to receive data sets 'Not ready for data’ false, by setting 
the line high. This of course i4 the same an ‘Ready for data’. 


Pinally, a vital concept without which nothing will muke scnse, The 'ATN? Une - 
read a5 ‘Attention’ - distinguishes between commands and duta. When {t is low, 
(tre), exch byte dnt is treated by all devices as a command, not an data. [f 
the command refers to m purticular device, that device becomes a tniker or o 
Halener and woith fer the handshaking process to begin, New the point is: this:- 
Oly ane byte carriva the Information tulling the devices which devicn ts to tik, 
ay, How Gun the devices distingutuh a ‘talk! command from oa ‘listen’? In fuet ench 
Canmand byte ia partitioned up, ao that the range within whieh the command byte 
Ne etermings its menlag. For example, if it ia Crom 0-1} decimal, the comninnd 
44 apecl type which we've got digenasee and isn't used off CUM michines. If It 
na fron 32 62, the command iso flsten address: If from 96 £26, a deconsdiry wddrans, 
il Nae uxamnpte, cansiiter the Commodeoce disk unit; this is deviee #8 Cuntesa mo dif 
the i he unlt bf mada a diatener by Cli Setlng ATN feu (0), CH) OHA #820 with 
isin ovies number, 4, and oa netting the velevant ‘listen address’ bitt iil) Sending 
nie a Gonna 5 tiv) aalting ALN falye (1), Further transnisukena will te 
iderstoud aa ASCiL., A secondary address will often be nent tou. 
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CBM IMPLEMENTATION OF THE tEEE~48@ BUS" 




































































ATN in {Attention “F 0 
_ATN aut a eer _ 059 2 1 
DAY in !Data Valid SE8hO (59456)/4 7 0 
DAV out $£823 » (59927) 3 1 
EOI in (End or Identify |sEB10 (59408) 6 0 
£01 out | > SEB! (599039) 3 1 
NDAC in |Not data accepted |5EB40 (59456)! a 0 
NDAC out [sEazt (59425) 3. 1 
NRFD in {Not ready for data seaue {59456}; 6 U3) 
NRED out i SE84O (59456); 1 1 
SRQ in [Service request $E823 (59427) a Oy) 
OATA LINES: 
Input : $E820 (59424) O-7 
utput $6822 (59426) 0-7 














a (440) 
b ( #08} 













input register 
c (#80) = ATN In, ¢& (#08} = NDAC out 
output register 

e (#80) = 5RQ in, f (#08) = DAV out 


iid hii 
Cine Bess 
0000 0000 
Cov. Foes 








DAV In, bh (#90) = NRFD in, J (#04) = ATN out, 


gh.. .jki| g (#80) 
NRED out, } (#01) = NOAC in 


k (#02) 


ua 





*Heferencam include: 

1) IEFE Std 489-1078 describes the 'GPIB' (General Purpose Interface Bus) and 
includss a full spocification, 

4$) Gregory Yob‘a three part article 1a Ellohbeud-Mlerocomputing (July - Sept, a0), 
‘get your PET on the TREK dus', bas w lot af informatlon tn about 23 pages. 
This includes hardeare oxamplus (e.€@- Wewlott-Packard clock und signal yenere 
ator, "Silmkin’ Cltea machine; , DASIG roulines to illustrate the workings of 
the bus, explanations of IEFE activity during Inpot/output fo.g. FNPUT# and 
PRINTS) and macnine-code rautines including some ROM lucatlona. 

41h} PET and tha [EKE-448 Rue (GPIB)' by Flaber ang Janeas (MeGraw-liz 1% 2940) 
deala wainly with old HOM PETs. The bock largely conalate of detailed broak~- 
downs of the BASIC 1/0 commands and lints of references- includiag Inatruaents 
uaing the IZEZ and a Libliography, It 18 hardware oriented; software exampiae 
include flowcharts, a DAYIC diagnostic program to report faulta on tha bus, 
and a singlo machino-coda example, & repring of a routing to drive an 
autronopical telaacope. 
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Meaning :- Machine 


Code:- 


BIT $6810 [ranch taken if input EOE {LDA $ER40 ;Wait until DAV in is high (false) 
BVC SET STlis high (false). ‘Branch if | BPL -5 f'Data not velid’, 
not end of input message’. 


Meaning :- 














LDA #334 L AUT $6840) Wait until DAY in is low (true). 
STA $EA12 |Get output EO! low (true) Ba Lu "Data valid’. 

LDA #$3C |Set output EOL high (faise),|.pa sra40 | Wait until NRFD in is false, i.e, 
STA $8811 |‘Not end of message’. AND #$40 = juntii 'Ready for data‘. 


LDA $2820 [Get a character from the BEQ +7 


EOR #$FF input register & reverse it-*|LDA $£840 iSet NRED out high (false). 
ceria ORA #S$O2 "Ready for data’, 
LDA #$34 ; h 
$34 |Sets ATN in low, and NDAC| Sf. S254, 


STA $E821 Jout low, ‘data not accepted’, 


Loa #33C =|Sets ATN In low, and NDAC 
STA $£421 |out high, ‘data accepted’ 


FOR #$FF |Store data (reversed) in 


| 

LDA #$ryD* |Set NRFD out iow (truc). 
AND $£840 |'Not ready for data’. 

STA $E840 | 


LDA $£840 iBranch taken If botn NRFD in 
STA $E822 + ffer.” Panay ; : 
Shas output burler AND #$41 jis high (faise} and NDAC in is 
LDA #934 |Sets SRQ in low (true) and | CHP #$4t high (false). f.e, "Ready for 
STA $6823 |DAV out true, ‘data valid’. [BEQ ERROR jdata' and ‘Duta accepted’ are 


LDA $£823 |Set DAV high (false). LDA $F840 Lbot FeUes 
ORA #908 |'Data not valid’. ano #$01 |Wait until NDAC in is high. 





STA $E823 BEQ -7 Data accepted’. 

LDA $E823 |Set DAV low (true). BIT $584D |Uses a VIA timer to detect time 
AND #$F7 |'Data valid’. BYS EAROR lout. ST=! if write, 2 if rend. * 
STA $2823 

LDA #$3¢) «| Sets SRQ in true and DAV 








out faise. 'Deta not valid‘. 


Set ATN high (false). 
‘Send data, not IEEE 
commands’. | 


Set ATN low (true). 
‘Send {EEE commands, not 
data’. 


$E823 


$E840 
ORA #$04 
$E840 
$zEa40 
AND #$FB 
$E840 











This table is Intenced for uae a3 an aid Ln understanding disassembled code, Each 
IEZE location appears In sequence, with the handshaking and control line mnemonics 
approximately in alphabetical order, Not all the possible permutationg and combin- 
ations are tisted, but those which are occur frequently In CLM ROM. Analogous 
6502 code exists within Commodore devices, to handle data transfer from the paint 
of view of those devices. 





soe ee ree ee eee see meee ae ee one 


Pi equivalent jn BASIC to reverse byte X 1a 255-2, 
This voriation hes af cnuren the identical affect ta LDA $RA4U/ AND #$FD. 
"In HASIC 4, time out may be lgnored by poking LdaU with any value > Lat. 
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+ 378- 


Programming the PET/CBH 
IEEE Command Groups 


14: Effective 6502 programming 








PPC{PPU 


GET|SPE 
TCT |SPD 


~ 
SemAMRUNseNeE SS 


[?) 
1 

2 
3 
4 
5 
6 
7 
8 
5 
A 
B 
Cc 
0 
E 
F 





ACG {Addressed Command Greup) includes: 
GET=Group Execute Trigger 
PPC=Paralle? Poll Configure 
TCT=Take Control 

UCG (Universal Command Group) includes: 
DCL=Devices Clear 
PPU=Paratlel Poll Unconfigure 
SPE-Serial Poll Enable 

LAG (Listen Address Group) includes UNL=Unlisten All Devices 

TAG (Talk Address Group) includes UNT=Untalk Ail Deviceg 

SCG (Secondary Command Group) holds CBM secondary addresses, except 

27Secondary address for CLOSE, Secondary address for OPEN and SAVE. 


GTL=Geo To Local 
SDC=Setected Device Clear 


LLO=Loca!l Lockout 
SPD=Serial Poll Disable 





Subdividing the command dyte sets limits on the number of devices controllable by 
the bug. 31 primary devices are allowed; secondary addressing was introduced 

to enable extra devices tu be connected, according to Fisher and Jensen, so that 
31x 31 = 961 is the absolute maximum. Commodore's use of the secondary address 
as a means of controlling the primary device is thercfore rather unorthodox. What 
does all this imply in BASIC? Firstly, the OPEN command for devices numbered 4 
or more (excludiig keyboard, cassettes, and screen) is designed to prepare BASIC 
for future comnmmnicition with the [EEE bus. OPEN X,¥,2,"STRING” makes three 
entries In each of three tables in RAM, unless these tables are fuil already. PEEK 
locations $93, 603, and 613 co take a took at this. If o file hag been opened, these 
locations will typically be 5,4, and 97. OPEN 5,4,1 will give these figures, the 

firat being the ‘logical fiie number’, the second the device number - here, 4, 4 
printer - and the third the secondary address with ita high nybble set to 6, adding 
Ju. (BASIC 1 has locutions $78, 594, $98 instend). Ef OPEN includes a “STRING” 
this {a sent along the bus and processed by the receiving device: normally this la 
a diak command, for instance "0:FILE,SEQ, READ” or “#" or *PROGRAM". Thia of 
course wets up A similar set of table entrics within the disk drive's own RAM, Now 
whut PIRINTEX,°MESSAGE" {4 executed, Ihe device aumbur ¥. and secondary 
address %, corresponding ta X are looked up in the tables. Y hes lta high nybble 
set te 2 by ORA 4$20, corresponding to LISTEN, ATN ja set low (true) and these 
bytes sent an conmandn; wien ATN in reset high, mil furthor output ia ASCIU data 
generated by the PRINT stalament and formatted in the normal CHM way. Finstly, 
PRINT # X senda an UNLISTEN te the bua directed at the printer. (It will alno send 
UNTALK if there bs an JREK output devies too; but usually Une keybourd or Kcreen 
provides output}, Note that OPEN ard CLOSE have aspect secondary addresses 
allucnted to them, #4 appearn in the flnal two columns of the table above, Thin id Dae 
reason for WOM routines Tike this; GOA kecondary acdresn/ ORA AFC, Aguin, it's 
& peculiarity of Commodure that thesa contrul bytes arg Interpreted thin way by 
CHM aqinipment. 
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[1] CMD, This BASIC keyword uses identical syntax to PRINT#, and operates in a 
very similar way,-the only difference being that the device is not UNLISTENed. * 
For thig reason it is used to keep open a file to disk or tape when a program is to 
be LISTed a5 & sequential file. Generally, PRINT# is easier to usc, unless a Lot of 
PRINT statements have to be changed, since UNLISTEN or other [EEE command 
may be issued by some other part of BASIC, CMD may be worth trying if data is 
to be sent simultaneousty to several destinations. In the same way that OPEN, 4: 
CMD4:INPUT"NAME":N$ within a program prints out NAME to the printer, not the 
screen, several files may be opened and printed to simultaneously; try for example 
OPEN1,1,1:CMD1:OPEN3,3:CMD3:OPEN8,8,8,"0:FILE":CMD8; PRINT "HELLO" 

which prints HELLO to tape #1, screen, and disk at one time. 
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{2] ATN. (Not arctangent!} Setting the ATN line low, sending a command, and 
setting it high again may be used to direct data to a recipient device. As an 
example, consider C Brannon's 'Keyprint’ program to print the screen contents to 
a Commodore printer (showing graphics and other Commodore features). The aim 
is to tell device 4 to listen, then set ATN high, then to output characters one at 
4 time, e.g. with SFFD2. When the page is finished, $FFCC, the routine to UN- 
LISTEN the printer, is called. and control returned to the interrupted program. 
ATN out is bit 2 of $E840. Unfortunately it is not enough to use machine code to 
load the IEEE output buffer with #44 - the talk command for device 4 - with its 
bits reversed, then lower ATN and put it high again, since this ignores the bus’ 
handshaking. The easiest method is to use ROM routines, although this has the 
drawback of causing the program to be untransferable between different ROMS 
without a few changes, LISTEN shares the same ROM area as TALK and in fact 
these routines are the very first in the FOO0-FFFF ROM. To cause device 4 to 
become a listener, the current device location ($Fl in BASIC 1, $D4 in BASIC>1) 
must contain #4, then LISTEN is called. ($F0BA in BASIC<4, $F0D5 in BASIC 4), 
Now ATN has to be set high. A routine which does this (i.e. sets bit 2 of SE340 
high) exists at $F132 (BASIC 1), §F12D (BASIC 2), or $F148 (BASIC 4). Also 
the current CMD location has to be set to #4, so that $FFD2 outputs its charact- 
ers to the correct device. This location is $0264in BASIC 1 and $B0 in BASIC>1. 
So with BASIC 4: 


LDA #$04 ; DEVICE NUMBER 4=PRINTER 

STA $D4 ; CURRENT DEVICE 

STA $BHO 3; CMD LOCATION (CURRENT OUTPUT) 
J8A $FODS; ‘LISTEN’ 

JSR $F148; PREPARE POX DATA OUTPUT 

eee ; PRINT CHARACTERS WITH $FFD2 
JBR $FFCC; SEND UNLISTEN 

oa CONTINUE 


as 


In this example, a secondary addresa was not sent. It could easily have been; 
3 bytes prior to the second subroutine, which sets ATN false, ls the entry point 
from which the contents of A are output to the IEEE before ATN is set false. 


{3] The PET ss controller. The first published account of spooling with the PET 
feomes to be T M Peterson's article in Compute! (Vol.3, #1 and reprinted in CCN and 
Transactor}. This method may not be foutproof, Jin Butterfleld, by coincidence in 
the same Issue of the maguzine, wrote that the logic {a not accurate enough for 
spuoting to be poysible, Peterson's method, for BASICs 2 und 4, is as follows:- 


*The commands LEITEN, TALK, UNLISTEN and UNTALK Use the imperative voice, su to 
Speak, To gake Wie punt clear ve can conmider human analoglea: conversationai~ 
Jet X way way to convernational imt ¥,"Listen, I want to toll you that..." amd 
thla uae of LISTEM ta siakiar to the LEKE'a. 86 Ia; “You've got five socoadsa to 
talk, or elac...” where the raciptiant af thls poesage ia belng dent a TALK 
Command, CHM equlpeent aslows only 65 wsilisgconde (.065 anc), however, before a 
VWeeulled ‘time oat orrer’. 

Ltha all ansiogiea, this one breahe down at soma pulnta, 
that ono talker only ie allowed on the 1ERE bua, 
lhatonera, 


The controlier ansures 
although there may be many 
In hema. commanicetijian of the other hand, no euch reatrictlos hulde, 
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pooling is a technique used to overcome speed limitations of printera: large 
omputer installations store their output on disk, then later disgarge the whole 
at, often at night. And the printers can be used when the processor is working 
‘ut has no printing to do. In principal this can be done with [EEE devices. The 
equence is: (i) Set ATN low (true). so the devices wait for commands. (ii} Send 
INLISTEN so that ail devices in LISTEN made no longer listen. (iii) Send TALK 
© device X: X is now the onty talker. (iv) Send LISTEN to device Y, (v} Now, 
et ATN high (false) ugain, having set up 4 listencr and a talker. These two 
levices will now talk and listen until the bus is used for something else, On the 
*ET, suppose we have a sequential fite on disk, which could contain data, oT @ 
yrogrum LISTed as a sequential file. The spooling technique goes like this: 


OPEN 7,8,9,"0:SPOOL,S&Q,READ": REM FIGURES CHOSEN FOR UNAMHIGUOUSNESS 
POKE 165,64+8: SYS G1668 : REM SYS 61695 IN BASIC 4. HIGH NibBLE 4=TALX 
POKE 165,96+9; SYS 61668 ; REM SYS 61695 IN BASIC 4. HIGH NYBBLE 6=3.ADD. 
OPEN 5,4: CMD $,;:POKE 176,3:POKE 174,0; AEM MAKE PRIATER A LISTENER 


7OKE 176,3 makes the screen the output device, 30 another program (not using 
‘he bus) may de run. POKE 174,0 sets the number of files to 0, so files Sand T 
ire erased. When the spooling is over, POKE 174,10: CLOSE 7 wil! close the 
jisk file, (Or you can OPEN 7,8,9: CLOSE 7). 


[8) Handshaking. The charts of implementation of the [EEE on the PET show 
pach control line (where used) except for SRQ having an ‘input’ and an ‘output’ 
sonnection. This meang that during handshaking. values set by the PET use the 
'output' location, but values being tested by the PET use the ‘input’ location. 
So the machine code which branches to itself when testing a line always uses an 
input location, while code which sets a value always uses an output line. This 
distinction ig of course a product of the hardware buffering methods employed. 
As an example, let's consider the ROM routine which outputs a character on the 
bus, This is situated immediately after the routine to send TALK and UNTALK, 
which sets ATN low before dropping into the routine and thus outputting a 
command. In BASIC 1 it's at SFOF1, in BASIC 2 at $FOEE, and in BASIC 4 at 
$F109. For copyright reasons it cannot be reproduced here, but the logic can be 
deciphered into this:- 


i. Set DAV fulse. ([.e. puta 1 into DAV out's bit in $£823) 

W. Check if both NRFD and NDAC are falae, If sa, the program stops with 
a %DEVICE NOT PRESENT ERROR, (l.e. uses bits from NRFD in & NDAC 
in, for tho test). 

li. Put reversed data in the output register $6822. 

iv, Wait until NRFD is true. 

vy. Set DAV true, and start the clock In the VIA. 

vi. Wait until NDAC becomes fulse, tf this doesn't happen before the timer 
clocks up 65536 microseconds, the status flug byte is set - in fact, #1 
fs ORA'd into it, which iv why ST of 1 means a time out error on write. 
Note however that BASIC 4 has a patch put in which enables this time 
out feature to be disabled, FOKE S0IFC (1920 In deeinal} with any value 
greater than 127 to make the device wait indcfinilely until the data Ans 
been aceepted, Commodore could, but didn't, include an option allowing 
the user to select his own time-out interval, 

viL.DAY Is set folac, 

viii. Finally, the output register is act null (with #FF!). 


This is the three-line handshake as Implemented on Une CRW, using the theres 
lines of the date byte control bus. Hewlett Mockard will aupyly cetala oF habs 
handshaking procedure, Thin, hawever, is approaching the hurd wre side of CHM, 
which bs net my intention. Hefore feaviag thes tuple Jet's briefly sen how toe wr blar 
one's ows handshaking routines for this bus. fa view of the oppertunities, thera 
seein ta bara strpriningty siaall aiourit of published work on device eonkrad witht 
the PET ZCRM, One populas set of routines, by Jotin Cooke, has appenred Wa 
Cemmedore publicallons, Cisher & fensen, Gregory Yoo'a urtieles, und, wilitasst 
acknowledgement, in the "PE Rovedied', mid this Is about all, However, prov leded 
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the details of the handshake are known, there should be little difficulty in writing 
routines which carry out the equivalent machine code. Asa simple subexample, 
suppose we wish to set NRFD false, wait untii DAV is true, then recover data 
from the input register. We look up these facts: 

i. NRFD out is bit 1 of $6840. 

ii. DAV in is bit 7 of SE840. 

fii. The input register is $£420. 
And the corresponding machine code might de:- 


LOA $6840 
ORA #$01 ; FOKCES BIT 1 HICH {IE FALSE) 
_ STA $E840 ; NOW, NRFD 15 FALSE. 
LABEL LDA $£340 
But LABEL ; LOOPS UNTIL HIGH BIT O (TRUE) 
LOA $EGZ0 
EZOR #SFF ; REVERSE DATA; NOW IN USUAL FORMAT 


[5] The status byte and ST. ST (also appears in the BASIC keywords reference 
section) is reserved in BASIC, so PRINT ST yields a value often zero, but, if mat, 
providing information on 4 read or write transaction on the IEEE bus or with the 
cassette tapes, which don't use the bus, but are programmed to look similar for 
consistency. ST is not a normal variable held in RAM, Instead, when ST is found 
in a BASIC statement, the value held in a single byte is Found and converted to 
ST, which therefore can't (normally) exceed 255. This byte is $020C in BASIC 1, 
and $96 in BASIC>1, Confining ourselves to IEEE transactions only, ST has only 
4vaelues apart from 0, which are 

ST=1 Time out errur on write 

ST=Z Time out error on read 

ST=64 End of messuge 

$1 2-128 Device not present. : 
These messages vary in value, ST +-128 may in BASIC cause the program to crash 
anyway. The time out errors can be useful; ST=2 shows the data hasn't been read 
although this may be obvious from the data itself. ST=1 is a bit incalculable. For 
example, some newer CHM priniers give this ‘error’ even when working correctly. 
And ST=64 can often be made redundant by the use of an end-of-file marker. Ir 
any case, EOI may not be refiable with some devices. However, in machine code, 
routines te read disk files often use ST's byte location as an easy test tor end-of- 
file, (f it is non-zero, the file is presumed to have been read completsiy. 


[6] ROM routines for use with the {EEE in data transfer. When using disk, madem 
or printer, the handshaking is taken care of, and beut left olone. But the ROM 
subroutines for processing data in machine code are of interest, providing As they 
do the posyibility of faster data processing than is ayuilabie with BASIC. All the 
‘kernel’ ROM routines (those in common between ull the CBM ROMs) operate with 
the [EEE and are often quite easy to une. Importunt RAM locations are: 


Length of mensage (e.g “0:PROG”’ has length G) $Di in BASIC>1, SEE inB.L. 
Logical file number $2 in AASIC>1, SEF in BASICL. 
Secondary address $D3 in HASICA1, $FO in BASIC]. 
Device number (primary address) §D4 In BAS(Cal, $F 1 in BASIC 1. 
Input device number, for input SAF in BASIC>1, $0263 In bot. 
Output device number, for output S$BO In BASIC? 1, $0264 in B.t. 


Ag an example, consider a machine-code routine to read CBM sequential files, We 
can open the Cite From HASIC, then rend with machine-code: OPEN 28,2, "DATA" to 
rend cequenthilly from the default device, for inatines, That 40% #927 Js $FFCB 
qete the devier for input ta the CUM. und JSR $FFCF Inputs a singte byte from the 
Avice. When reading i conipiete, Ja SPPcc lows the fi, To open a file from 
inachine code requires UWiat Cie parameters In the tajle abave are vet, ined tht 
GETCUR points to the ateet oY the string. Then JSA $PFcu culty the OPEN cewtine 
wae) by BASIC. TERE raulites themselves can be called, although the pend] Cing 
code te nat iranstersble between KASICa, For mxainpte, In BASIC 2, {fa files is 
ooo, LDA #04/ STA FLA? ASR $FOuas LUA #§0d/ STA She JAR SPLZkK performs: two 
Funetlonn, firstly setting deview ae Che dak drives) te tbe cr file is preted to 
he open -omnd qutputlingg the seenadary aiblresa 3. Now, Joa Sp yac brageuat am sanpeder 
Character along the VERE bua, Phds method Es odnerd, BUDA aecetdary adele 4 i, 
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by ‘Universal Wedge' for DOS, to read characters from the error channel. Commands 


mey be send to the disk using the error/command channel with secondary address 
15, which of course has to be OPENed with OPEN 15,8,15 or same other logical 
fite number early in the proceedings. This routine ilustrates the method: 


LDA #$08 ;DEVICE NUMBER (PHIMARY ADDRESS) 

STa $04 :STORE IT. 

LDA #$6F ;SECONDARY ADDRESS OF 15 (HAS HIGH NYBBLE = 6) 

STA $b3 STORE IT, TOO, 

JSA $PODS ;SEND 'LISTEN'. (THIS IS BASIC 4. BASIC 1l=$FOGA, BASIC 2=$FOBA). 
LDA $D3 ;LOAD SECONDARY ADDRESS 

JSR $F143 ;SEND IT; ALSO SET ATTENTION LINE HIGH {FALSE}. THIS I9 BASIC 4, 


LABEL LDX #$06 ;BASIC 1=$F12C, BASIC 2+$F128. 


INC $77 

LDA ($77,%); LOAD NEXT CHARACTER IN SUFFER FAOM $0200ff. 

BRQ EXiT ;ZERO BYTE MARKS END OF COMMAND STRING 

JSR $F19E ;HANDSHAKE THE BYTE OLT. (BASIC 1=$F167, BASIC 2=$P16F) 
UMP LABEL ;CONTINUE LOOP, OUTPUTTING CHARACTERS. 


EXIT JSR FIB9 ;SEND ‘UNLISTEN'. (THIS IS BASIC 4, BASIC 1=$F17E, BASIC 2=$F183). 


Other Ratures. notes, and bugs related to the [EEE bus. 





[1} Functions not implemented by CBM. <A large number of IEEE funetions don't 
exist on the CBM, but can be programmed along the lines stready discussed, It 
appear’ from Fisher and Jensen that cny function can be programmed {pp.155 ff.), 
Presumably this can only de accomplished after hardware modifications should a 
function require the use of one of the interface lines not currently wired for the 
purpose. These lines are the {FC line, the REN line, and the SRQ line, which is 
wired for input only. IFC {interface clear) is a reset line; on switchon it is set 
low as a hardware process. REN (remote enable) is grounded, hence ‘true’, to 
retain CRM control over the devices. SRQ (service request) for the same reason is 
not wired for output from the CBM, which is the controller. 


[2] Bugs. BASIC 1, not surprisingly, has & number. LOAD, SAVE and VERIFY 
don't work properly with disks (and have tape bugs (oo). The hardware connect- 
jons to the PIAs and VIA cause some problems because of interactions. When the 
serecn acrolls $E811 was poked to blank the screen; thin also sent an EQ] out. 
This bug was carried over into BASIC 2. BASIC 4, as we've seen, has a special 
location to enable the time out feature to be switched off; 65 milliseconds was in 
any case an arbitrary figure. [ff it is off, though, the stop key is the only exit 
should a device not respond, All ROMs prior to BASIC 4 have a bug in theic 
UNTALK/ UNLISTEN routine ($FFCC}, where ATN is not act low when #$5F, the 
command for UNTALK, is sent. G Huckell (Compute! Jan.‘31) wrote that a device 
may become wrongly enabled, or single characters last or treated as command, 
because of this. When using $FFCC, therefore, on earller ROMs, It is advisnble to 
set ATN like this: LDA $&#40 

AND #$FB 

STA $Eu49; ATN NOW LOW (TRUE) 

J5R $FPCC 
Huckell also wrote that CYM aquipment is ‘immunc' from this problom. Probably 
only those userg who are trying to connect other JEEE equipment need concern 
themactyes with this. Relocation of some ROM routine into RAM may be the beat 
way of actually writing In the patch. 
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14,8 FIAs and VIA. 


These three chips control the keyboard, cassettes, screen, IEEE bus, and user port. 
Both are 40-pin devices with two ports, invariably called A and B. The ports are 
independently controlled anc (apart from certain smatl differences) almost identical, so 
each chip can be considerec to be made up of two similar halves. The PIA or 6520, 
(Peripheral tnterface Adapter’). is memory-mapped into four bytes, of which two are 
porta; the VIA or 6522 (‘Versatile Interface Adapter} occupies 14 bytes, of which 
three are ports, two of them altcrnatives of port A. In all PET/ CBMs they occupy 
these locations: 
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PIA 1}... £810 - E81) . 59408 - 5941 
PIA 2... E820 - E823 «-» 59424 - 59427 
VIA... E840 - E84F -.. 49456 - $9471 


{CRT controller in 12-inch screen CBMs ... £890 - E8si]. 
The peripherals are not wired in a very systematic manner, as the section on the IEEE 
bus showed. Before describing the various parts of these chips and explaining their 
programming, [ draw the reader's attention to the following program. This is written 
for BASIC 2, and is a retocatable routine which loops. displaying eight-bit byte patt- 
erns on the screen, with their addresses. The range of addresses is controllable by 
changing the marked bytes. And different ROMs can be catered for: disassemble the 
routine and change the four ROM addresses from BASIC 2 to BASIC<>2, with the help 
of Chapter 15: 


ETTS Print A ap two aybbles. 
FOCA Print two spacer. 

FOOD Print one space. 

FoOO Print carriage return. 
(PFD2 and FFE are karnel 
routines]. 


033A A9 13 20 D2 FF ag (8) 85 
0342 02 a9(40)85 01 AS 02 20 
034A 75. £7 AS 01 20 75 FE? 20 
0352 CA.FR AO GO BT OI 85 90 
035a AD 30 06 OO 90 02 AD 31 
0362 20 D2 FF cB CO 08 FD 09 
O36A CN 04 DO EC 20 CD ER DO 
0372 £7 20 DO.FG £6 01 a5 01 
037, €9 0) DO C9 20 £1 FF BO 
03482 B7 00 


DISPLAY BYTES FROM $£840 - SE84F. 


This breaks to the monitor on Stop; put #$60 into $0383 to return to BASIC. The loop 
repeatedly homes the cursor and displays the VIA‘a contents, so the timers for exam- 
ple can be seen moving. If the loop is removed and the routine prefixed by SEl, it 
tan be incorporated into the interrupt to give a continual display of the chip's cont~ 
ents. Either PIA can be watched when required. 


14.8.1 The PIA. This chip. though simpler than the VIA. 1s nevertheless consider- 
ably complex. Let's look at its features and the names and abbreviations given to each 
of them. First, we have the two ports, A and B. These are 8 bits held in a single 
byte or register: the individual bita are referred to aa PAQto FA? in port A, and 
PBOto PB7 in port &, Each bit can be configured for either input or output; very 
often ali @ bits are configured identically. Peeking or poking, and the muchine-code 
equivalent, 4s used to take data from the registers and write {t into the registers 
respectively. The registers mary be called (/ORA or (/ORB, input/output register A or 
register B. Each of the two ports hay two contro! Hines; each occupies one pin, so the 
ports have tO bits euch if these lines are used. Port A has control lines CA? and CA?2, 
and part B has CBi and CA2. CAL and CBI are uanble only for input; CA2 and CH2 
may be defined either for input or output, The ports therefore occupy two Dytes of 
the memory-map, the othe) two bytes, which Include fings to check the status of the 
control lines, are called control registers, CRA Ceantrot reginter A’p and CRA ('eont- 
rol register BY) correspond, unsurprisingly, to ports And H respectively. When the 
control regiiter ig appruprively vet, ils pert no longer reevives or sends data, but ta 
treuied instead an a duty direcHon register, the pattern of blis being loaded into it 
Gefining ity bits as inpatx Owhen bit : 0), o¢ outputs (when bit= 3). DORA ard OORB 
are the data direction registers for ports A and B, Their Joentiong are the same a4 
those of the ports; bit 2 in the contral cegister determines whether the reyister La 
cuerently trested ay a date direction regiater or a port. When bit 2 {4 zero, DDR Ix 
Wieumed, and the value da the direction reglates when bit 2 rises ta Toulefines: whieh 
bity will be treated ae input and which a4 ovtput until the ayatem ba redefined, This 
errangement th economical, Of a Tittle vonfualng, Nate that on switehlag on, the chip's 
Internal mechanism eet» all registers to zero, so that a date direction is resumed: in 
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which all bits are inputs. This prevents hardware connected to the system from being 
turned on with the computer, PIAs have two interrupt request lines, (RQA and (RQB. 
These are normally high, but may be programmed to become low when g@ change is det- 
ected in CAL, CA2, CB1, or CB2. Alt these interrupts, if they occur, can be dist- 
inguished by software; in the PET/CBM, only one interrupt (corresponding to the 
screen refresh) is enabled, so the system of Mags in the control registers is not used. 
At least, this is generally true, with the exception of tape operations, which detect 
and control the cassettes by means of interrupts and the control-line CAL on PIAL 
and CBt on the VIA, Interrupts can be defined to take place upon cither of two types 
of transition: ‘active low’ means that a transition from high (1) to low (@) triggers 
the interrupt, and ‘cctive high’ means the opposite - that the relevant control -tine 
must rise from low (0) to high (1). If a triggering transition takes place, it is called 
an octive trensition. Transitions in the other direction are not active. Even if the 
interrupt request enable is off, a flag is sct in the chip whenever an appropriate 
transition happens; these flags cannot be turned off in the normal way. with a poke, 
but instead a peek is used! Reading the data from the register (i.c. the port) resets 
the interrupt flags. The control lines are intended for use in handshaking applications 
and, as we'll see, the JEEE commands described in the previous section are of this 
type. Note that the controi lines are net present as bits in the PIA. The programmer 
can tell the chip to set one or other control-line for output, and set it low or high, 
or detect changes in an input, but there is no bit in either register which directly 
reveals any control-line’s current status, This is a rather confusing point until it is 
understood. 

Having made 4 stab at a verbal explanation, let's look at the same material diag- 
rummaticalty in the hope of reinforcing whatever learning may have taken place. We'll 
consider PIA 1; PIA 2 is internally identical, but has different RAM locations and, 
because it is connected differently, has other functions than those of PIAL: 
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RAM ADDRESS: - BITS: 
Eald ($9408) CAL [INPUT] + CAZ [1/0] + 
B812 (59400) 


76343210 


(Cro Fl 
E512 (59410) f { [ j | 1 } 


The ports. As wo've seen, these are relatively straightforward. Bit 2 of either control 
register switches its own port between a data direction register when the bit {s zero. 
to a port when the bit is 1. Example: how du we configure port A for output of all 8 
bita? First. bit 2 of CRA must be set to zero; then #FF is stored in DORA: then bit 
2 of CRA is reset to 1. ‘This program (or the BASIC equivalent) will do the trick: 
LDA EB11/ AND #FB/ STA ¥811/ LDA #PF/ STA E@iC/ LDA £F811/ ORA #04/ STA Fil 

In the game way #00 configures port A for input on all @ lines, #AB configures bits 
2,4, and 6 for input amd the rest for output. 


PORTA or DDRA 


C81 [INPUT] + CB2 (I/O) + PORT_B or DDRB 


The control registers. We can Ignore bit 2, which we now know about, The only other 
function of the control registers is control of the lines CAL and CA2 (by CRA), and 
controt of Chl and C2 (by CRB). CAL and CB1 sre for input only, and have one 
fewer controling bit than CA2 end C2, 3 bits us oppoyed to 4. The dingram shows 
how the seven Ults are dlvided, Bits 7 and 6, the two high bits, are interrupt Rage of 
control - Hines 1 and 2 respectlyely; the BIT instruclion can tes. both, which heips 
explain tha frugmented layout. 

Control lines as inputs. When bit 5 of u control register Is zero, controi-line 2 
ta configured fur input. This option ls aot avaituble for control tine f, whieh [is alway 4 
an input. We can dent with these situations together, beeause ench ting ds contratied in 
the anme way when controlling 2 Is an input. Hemembering that bits 6 and 7 re flags. 
Aol controllable ty direst poking of datu. we have onty bits [.1, und 4 left. Of 
these, bite O and } control tine I, and bits dand 4 control Hie 2. Their effects are 
ta act the direction af active transition, and to enable or diwabie the interrupt re- 
quest ling. (Fhe iterrupt flags are always set on actlye trinsition, but [iQ nrud nol 
bo). This toble summarises the astuation: 














i a 
SIT NUMHER: 1 [CTRL-LEINEL} or 4 [CTRO-LINES] 


BIT BET TY 90: 
BIT SET TO 1; 


O (CTRL-LINES] or 3 (UTRL-LINE2) 
a 


a 


Sets artive transition nogatlva Hisahles lHQ autput 


Bete active transition poumllive | Bneablee FRQ gutput 


—_ —— 
"Nolte: Unis program is an tilums$ration anty; LL may be insidvine pie to racentigure PETS: 













. 


ROO ES IE OUTED TE I ATE SAGE SET oh VAMP TRIS ROE TOA ee err omit Meee garments = © 


a eR RN Oe TE la tae ath elt 
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Programming the PET /C8aM ~385~- 


Control-lines CA2 and C82 as outputs. When bit 5 of either control register ‘3 
set high, CA2 or CB2 respectively {or both) become configured for output. The two 
ports are now somewhat asymmetrical if handshaking is used. If it tsn’t, both ports 
behave identically. Let's look at this situation first: 


BIT $=1 [CTRL-LINE 2 OUTPUT) and BIT4=1 U'MANUAL OUTPUT' WITHOUT BANDSHAE iG } 


Now, BIT 3 HIGH SETS CONTHOL-LINE 2 HIGH, 
BIT 3 LOW SETS CONTROL-~LINS 2 LOW. 


Thia le the so-called manual output, where CA2 or CB2 can be set high or low as the 
programmer pleases. 


Qutput with handshaking is the most complex option: 
BIT Sel [CTRL-LINE 2 OUTPUT] and BIT 490 [OUTPUT WITH HANDSRAKING] 


Now, control-line 1 Is configured (as always) for input, and control-line 2 for output. 
It ig this which makes handshaking possible, the input bringing a signal from the 
device, and the output line sending a signal, The port itself can be used either to 
read or write, and CA2 handshakes on reading, C82 on writing. That is, CA2 is used 
with LDA and similar instructions, CB2 with STA-type instructions. The sequences are 
these: : 
BIT 3 LOW with CA: CA2 15 now controlled by two events: 
(4) CAL active traneltion sets it high, 
(41) Read operation sets it low. 


BIT 7 LOW with CB2: CB2 ia controlled by two eventa: 
(1) CB1 active transition seta it high, 
(11) Nrite operation seta it low. 
BIT 3 HIGH: Causes ‘pulse output’, CAZ or CB2 going low for one cycle only after 
read or write operation. (This pulse may be too short for aome uses) 


Refore looking at examples from the PET, the reader might like to examine this summ- 
ary diagram of the PIA, which includes most of the features mentioned. If it seems 
rather confusing, please don't blame me! 





on Read=0 
Pulae a 3 





CONTROL 
REG- 
ISTER A. 


IRQ off. 0 


Port B und DDR are identical, except that CRU = xx1G Oxxx implies read handshake, 


Examples. We ean follow the reset vector from (SFFFC) In ROM to find how the PETS 
Woinhlilises Its PIAS. Diagrams on the next page skow how the ports are connected, 
and the uacs of the control lines, and thease may be compared with the initialisation 
Joyte to seo how wench PIA works, Considering PLA i fest, ignoring other (/O chips: 


RESET ... ALL REGISTEAS NOW HOLD O .,. 
LDA #OF 
STA £410 ;THIS IS CUARENTLY UDMA, 80 WH HAVE FOUR IMPUTS AND FOUR OUTPUTS 
LDA #3D 


ATA EKL3) ; DDR IMPLICITLY LAFT WITH #0, f£.0. ALL INPUTS, CGONTAOL REGISTER 
[A ENAWLES C1 INTEARUPT WITH ACTIVE LOW, AND SETS CUZ HIGH 

BIT ZH13 {SEMMN TO UZ INTENDED TO CLEAR [NTERKUPT FLAGS IN EKL3 

LUA wD 

HTA EBL] ;SBETCHES TO PORT A PROM OHA, DtHAHLES JNTERAUPTS,; GETS CAZ HIGH 


Thus, bite 4-7 in port Aare for Inpul, ant bith O- 3 for output; thin bea tateh of 
Hits {a used with port H (configured for output) when reading the kayhourd ducing 


. 


ian :— _ erent : 
Pr nye sar nih AE NEUEN SPO A TUS CE A ARMOR rT MARR! SIT Hie ~ Am a a eM RT EL ETAT: —— 
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\e interrupt processing sequence. Note that an interrupt is enabled on a CBI trans~- 
ion. This is the interrupt which drives the keyboard processing. Now let's look at 
ve second PiA, again lgnoring the other chips‘ initialisation: 


RESET ... ALL REGISTERS NOW HOLD O ... 


LOX wFF 
STK EB22 ;TRIS 19 CURRENTLY DDRB FOR THIS CHIP, SO IT'S CONFIGURED FOR 


;QUTPUT ON ALL 8 BITS 
LDA #1C 
STA £821 ;DORA IMPLICITLY LEFT WITH INPUTS. CAa £9 SBT FOR OUTPUT & HIGH 
STA E823 ;CB2 19 SET FOR OUTPUT, AND IS SET HIGH 
STX EE22 ;PUT #FF. AS OUTPUT OF PORT B, BECAUSE IEEE 'LOW' (S 1 AND v.¥, 


IA 2 is used only by the [EEE bus. its programming in ROM reflects this: the input 
ort (A) is read and EORed with #FF to flip its bits, and conversely data is reversed 
nd stored in the output port (B). The output control lines CA2 and CH2 (-NDAC and 
\AV out) are set alternately high and iow by storing #3C and #34 into their control 
egisters, setting bit 3 on and off. PIA 1 has more variety: a search program (e.g, 
lunt from Supermon) can track down the forty or 30 occurrences of ROM calls te add- 
esses EB10- £813, revealing testa for input bits in port A, keyboard reading routines, 
ape routines which disable Lhe CB1 interrupt and later reenable it, and scme CAz 
utputs which are relics of BASIC i. 


D S8408 PORT A Te eee 












Kefboard rdw (0-9) 


1 89408 “CONTROL [Gaueoutput to blank the[Port & |cAl=cassotte #1 
REGISTER | trans’n{trans‘n | screen old PETs only) |or DDRAlread Ling 
A |” seorfout (CBMs) awitch \ 


2 $9410 “PORT B | -------4----- 7 Toareaa bo ENPLTS—~- == penaoe n= Sarees pees 
Contents of k¢yboard Fow | 
,jall bits pet, ot all but one} 


3 $9411 CONTAOL | CBA Port B CBl=scre¢n ‘ex 
RECISTER |] trana'n|trane’S or DDRS trace life in 
8 flag switch { 


ey ES ES Liable = INPUTS 3 ---- ae =—eeee 
dout puffer for the IEEE un 

















2) «469424 PORT A 
















2) 68425 CONTROL {CAL {CA2 i ' A } t 
REG'R A trana'n|tranea) | CAZ Line = XD q eM J DBRA 


22 80426 PORT B 


23 §9427 CONTROL 
REG'R B 


14.8.2 The VIA. This Input-output chip ta another 40-pin device, which includes 

all tha a Ceatures ag a pubnet of its own. As we shall see, the arrangement Is 4 
little different. The PIA is a predecessor of the VIA, ao If the previous section of the 
vhapter ha» been understood you will be well equipped to tackle the cather greater 
complexities of the VIA. All this is something of an electroni¢a engipeerta# speelat iam, 
and $s not needed in munt programming woleds it's Gayertial (a write or cegivher [/O 
routines. The usual sources of Information on enips of thia sort are fren date shots 
from the muanulaclurer, and Ln feet inany booka on the subject quote from these with 
litte attempt at cauprehansibte explanation. Eve Urhad ta present all Lhe important 
adpects of the VIA Ino rendabie form, slurling with a deseriptiorr of lhe eatra regis: 
tera passesaed by the chip, 4 Wagram of the PRT CUM individeal implementation nf 
them, und finely program examples xhowlng bow wech type of facility 14 tuned. ‘Pat 
examples ace in machine code: BASIC equivalents are casily weitten, usually by direct 
conversion into peek and puke commands operatiig an decimal sda renses. 


Draken acini ltt aaa Dalal oe ean ii Cait aia eae 1S YD RT A LAR I AT TS eS ART . 


* eee, 
SR tee ee em cect Pe ee a NR AR Tega SE ter 


Programming the PET /C8M -287- 14: Effective 6502 programming 


The ViA has two ports, port A and port B, each of which has a separate data direct- 
ion register. Port A can be written or read or both from two separate locations; there 
are two port As. The some data appears in esch: the differetice is that one has a 
handshake effect with CA2, the other having no such effect. Rather confusingly, port 
B appears first in the RAM addresses, followed by the handshaking port A. CAL and 
CA2 are control lines for port A, CBl and CB2 for port B, and, as with the PIA, the 
CAi and CB1 lines are always input jines, while CA2 and CB2 may be configured for 
either input or output. Note that every PIA and VIA has fits own control lines; the 
similarity of the names should not (although it might) cause you to think that the 
name 'CAl' say refers to a unique wire somewhere. 

The VIA occupies 16 RAM addresses, 12 more than the PIA. As we've seen, 
there is an extra 8-bit port and two data direction registers to account for 3 new ad- 
dresses. There are also 6 registers occupied by timers, 1 by the shift-register, and 
4 by the control registers. which between tnem include the PIA's CRA and CRB. We'll 
see very shortly what these registers do and how they do it, but let’s first look at 
famitiar parts of the chip, which resemble the PIA. The ports and data direction reg-~ 
isters are similar (but do not need 4 bit to switch from one to the other), as are the 
control fines. On reset. values are set zero, and the usual conventions apply with 
respect to bit settings: A bit value of 1 (a) sets a line high, (b) configures a line for 
output, (c) defines an active transition as positive (i.e. 0 to 1), (d) indicates that an 
active transition has oceurred, or (e) enabies an interrupt to happen when a line 
receives an active transition. Zero dit values of course mean the opposite. As in the 
PIA, flags which show transitions cannot be set by pokes, but instead are set only by 
hardware transitions and cleared only by peeking or poking certain related locations. 

The user port (the central connector at the back of the machine) is conrected 
to the VIA: pin B (an the underside, second from the left) is CA1; pins B - L are 
port A; and pin M is CH2, CAl is an input line which may be used to handshake with 
port A, which is the reason for its inelusion. CB2 is connected to the shift register, 
and can be used to deai with serial processing. Of the other control lines, CA2 is 
responsible for the graphics or lower-case switch in the character-generation, and 
CBI is used to signal input from cassette #2. 

Taking the new features of this chip in sequence, we have the following: 

Timers. The VIA is equipped with two 16-bit timers. These are timers 1 and 2, 
or T? and 72. Each takes up tno a-bit registers. Each is set for input on power- 
on, in which mode counting takes place; when a value is londed into either timer it is 
set for output, decrementing once evcry clock-cycle. A maximum cycle of about 1/iSth 
second (from #FFEF to #0) can be timed. When a timer reaches zero an interrupt fag 
is set, but an interrupt occurs onty if it is enabled. Timer T1 has a special feature. 
namely a fatch. Thig is a second 16-bit register which allows 4 vatue to be stored 
until it is moved to the timer proper. When Ti reaches zero. the latched value is re- 
loaded and the process repeated, so the time-intervals batween timing-out are vuriable 
within a large range, though with a i/15th second maximum. in this way, Tl tukes up 
4 bytes, and T2 two. The rule to remember ig that reading the low byte of either 
timer (but not the iatch} clears its own interrupt flag; and writing to the high byte 
clears the flag and starts the timer counting. This means that sequences of interrupts, 
and one-shot interrupts can be used, end that new timer values must bo londed with 
the low-byte first if exact timing is required, ¢.g. 9 lapse of #1234 microscconds 
exactly. 

Ports A and B cxn also be lotched, vo that on an active transitlon of CAt, the 
value in port A is retained indefinitely (or untit the next active transition on that pin) 
and slmilurly for CHt and port #. This ta useful of couese in many input applications 
where H may be impracticuble te continually read the value at a port. 

The shift register. Thia & bit register In connected to CBZ. On gommand, Che 
shift register perforum @ shifts, having the offect rither of moving Gut 4 bits singty to 
CH2, or of inputting B bits from Cliz one at # tine. The cammand [x analogews ta ASL, 
where CH2 is oqulvaient te the corry flag and the shifted luuention (aay A} corren- 
ponds ta the shife register; Uf this ia repeted elghr times, the byte contained In the 
shift register has been output in serial form, one bit at a thie. There Inn’ a command 
quite analogetin lo shiftiag ing LS lakes ina tere fit. 

The shift register cun be thued ty T2 (see the music example dt Chapter 9), and 
at the same rate asx the 6502, using the ‘phase two clock’, dt. Altupnatively mpother 
external clock may time JO. The is therefore 4 versatie regixter, whieb with suitable 
haniwore experiiae - @acufuia Cie see port's u4efulneda a ygteat deal, 
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The Auxiliary Control Register (ACR) controls the timers, 
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the shift register, and the 


latch status of ports A and B, The disgram reflects the conceptual arrangement of bits 


7 -@ across the page. The shift register 
combinations, which explains its appsrentl 


used and are unlikely to be). 





control hag three bits, and therefore eight 


y excessive prominence. (Note: Timer 1 has 








































ACR?T ACRE ACRS ACRHY ACR3 ACR? ACRt ACRQ 
EsaB $9467 TIMER? CONTROL | TIMER 2| SRIFT REGISTER CONTROL | PORT B :PORT A 
uPB7  OLONE’ | SON FROR | | EATCH | LATCH 
UNUSED SHOT ([0-ONE | GOO<SHIFT REG. DISABLED|O=D1S- | 0-DIS- 
A=CONTIN4 SHOT | sox-suirt IN BY TIMER 2| ABRED | ABLED 

SCOUNT | OLO=SHLFT IN BY 2 [isBN- | 2<EN- 
O11=SHIFT IN, EXT.CLOCK; ABLED ; ABLED 
100=FREE RUN BY TIMER 2] ON CBL : ON CA1 
101=SHIFT OUT BY TIMER 2| TRANSN | TRANSN 

110=SRIFT OUT BY a2 | (IN/ CIN) 

LIL=SHIET OUT, EXT.CLOCK| OUT) 












The Peripheral Control Register {PCR} controls the operating modes of the four 

CR2 and CA2 sre allocated three control bits 
in this register. CBL and CAL are allocated one each. This register therefore [s very 
like both CRA and CRB of the PIA, but without the interrupt flags (which have been 
moved to the interrupt flag register (below) and the active transition pit for CAL, the 


control lines CAi, CA2, CBl, and CR2, 


switch between DDR and Port is omitted. 
to the interrupt enable register. 


its only effect is on the clearing of the int 


This means that CA2 


The interrupt enable flags are also moved, 


cleared by reading or writing the port, bul with 0x1 is cleared only by writing bit 


into the correct bit of the interrupt fag 


PCR7 PCRE PCRS 








ES4¢ 39468 


a0 
CB2 hi=L 
CB2 losd 


register. 


PCR3 PCR2 PCRI1 


CA2 CONTROL 
t 
Direct-; Hand- |on Read 
ton:) ahakesO = 


PCRA PCRO 





transo: 


Highsl | 1-00r  CAZnieT 
| a = ! 
Low #0 j Manual=li ogg Lond 





Active [Clear | 
High=l |IFR = 
Low 20 |IFR/OAB 








Clear 
O=nIN { Highs 


ractive |C¢ 
I Low =O 


The Interrupt Flag Register (IFR} and the Interrupt Enabte Register (HER). 

These registers are symmetrical wilh respeet to cncit other and can be considered to 
gether. The first indientes whether on active transition has necurred, und, If 80, 
which WIA device coused it. it atso signala whether an inte rupt took place - Jf the 


corresponding interrupt was 


pat ennbled by the LER, the Muy, though sect. won't 


cause an Interrupt. [ER7 vontrols the function of the rest of TER: when 0, eech bit 


get to 1 Clears itn correspunding Interrup 


its interrupt enable bit. 
(FR? 1FR6 IFRS 


TIME 1 | TIMER 2 
HNO IRQ] GUT 













Baad «Se4dd 


SER? JERS iERS 


t enable: when TERT=1, each bit sat to 184 












j OUT | THANSN 
rt rere 


\FRa IFR3 IFR2 IFRI IFRO 

cal 1CH2 |BILEET cal (cut 
[TAANNN [REGISTERD TRANSN TRANSN 

IERY {ER3 HER? {JER1. JERE 


wha SHIET RGR) CAL ; Cad 
| | 
i ae eee 





a 
£e4z 60470 | inl ENABLES [TIMER 1 [TIMKR 3 | CBI 
0») DISANLEH } 


ee RE Te RRR ee te in enti re mn meen tl 


ee ey eR TE ED tint ce near nen a ie aecarting FU 


effects on bit PB7 of part 8; U've iguored them here for simplicity, since they aren't 


and CB2 have on extra dit, and 
errupt fleg, which with pattern Ox0 may be 


1 


is 
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ga40 59456 PORT B 





Bs41 $9487 PORT A* 













E844 $9453 DDRB (values 
on set-up showm) 
£943 $9459 DDRA 





zs44 59460 TIMER 1 LO 


£B45 59461 TIMER 1 H1 





£s46 $9462 T1 LATCH LO 


£847 59463 Tl LATCH HI 





Faaa $9464 TIMER 2 LO 





Ee49 59485 TIMER 2 HI 





Ea¢a 89466 SHIFT REG'R 





PORT B| PORT A 
LATCH | LATCH 


gaan $9467 ACR (eet to SHIFT REGISTER 


TIMER 1 TIMER2 
#00 on power-on)| CONTROL CONTROL _ CONTROL = 1 LATE! 
2a4c $9468 PCR (set #OC on CB2 CONTROL? CBl? | CA2 CONTRUL? CAL? 
ROE on power-on)| (USER PORT PIN M)  CNTRL (GRAPHICS MODE) —_|CNTRL 
Eaqp $9469 IFR {set to [IRQ Tr 0 tz cBI SH-REG! “CAL | CA2 
#00 on power-on) jon /ott NT |. INT INT INT INT 
Ba4E 39470 [ER (aot to to oT! cBl 
#80 on power-on) dimsabl L. 


” 
Bear $9471 PORT A USER PORT without CA2 handshake 

















*Ea4P (59471) is the preferred user port register, aioce CA2 controls acreen graphics. 
‘The sotor is on. when this line is low, and off when if is high. 

ICAL 4s connected to pin 8 of the user port. Pins B- L correspond to port A, which is 
invariably E845. CH2 (cannectedto the whift-register) also connects with pin M of the 
user port; square-wave tones (see Chapter @) use these facts. CB1 signala input from 
Casnatte #2, CAZ controls screen graphica: it ts configured for output, and, when low, 
gives lower-case charctere and others. When high, the mode ia upper cane/ graphics. 


implementation of the VIA in the PET/CBM system. 


Examples of ViA_programming: 


A PET/CAM's VIA contents typically r embie the fk ae 
hee: 3 cay Te a. en ie B 
diugram (right). Mote thet the act ef pecking some Oa eas ea heh A 
registers resets the corresponding Interrupt flag if £842 0011 t110 DORB 
it ia get, so [FR may not be accurate. Port A is E43} 0000 0000 DDRA 
configured for input, a» it is on awitehing on. ga44 3100 1100 Ti LOW 
Port B ts configured for output In the usual way, e345 1191 1911 T1 HIGH 
except that bit 4 is set for output, to enuble fugt- bat La we TIL nae 
Nereon printing with HASIC 4 onfy. Buth timers Rian 0910 0101 ie 
are running; Ti nas been set to #PFFF. The shift yaaa 1191 0090 72 HIGH 
ropister holds #FF, in place of the usual #0, huv- Elda 1117 1011 SITET ARG 
ing been used far square: wave music. Ft ia at “H4A 0000 O00 acR 
preaent disabled: ACR is #0, its nermel value, POR yAdC 0000 1190 PCA 
nolda deelmol 12, 4¢ the maching Iain upper casas EN4p 66000 9990 TR 
graphica modu. No use is belng nade of CB2, FR ae ee pet ads % 


shows that no fkQ@ bas taken place, and bo Maga to 
dengta transitions on aay uf the T lines ure aot, but 
fhead would in any cane have been cloarad by the 
program, which ceada from EH4U0 through Ka4e, LER 
rhows that no transitions «ill genarnte laturrupte, 


TYPICAL ¥IA_ConTENTS 


Er RS SR, on aac ena ne aT IE AR ete TTS ee Ap ere Sn aeiain ae 
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Programming the ports Port B handles a great deat of [EEE character inputand out- 
gut, in addition to some tape handling. 7 bits are therefore initialised on power-on, 
ind there ig little reason to change them via DDRB. Bit 5 can be converted to output 
node: in BAS!Cs < 4 this accelerates screen writing. because screen retrace is no long: 
or awaited before a character is poked into screen RAM. Port A is unused by the CSM, 
ilthough some hardware (e.g. Compu/think) uses it. in principle it is easy to use: the 
right bits of port A are connected to the external device, and CA1, also on the user 
sort, signals data transmission by its transition from (say) low to high, which, when 
detected by the PET/CEM, reads the data from the port. perhaps having latched it. 
Conversely, CBZcan be configured for output and used to signal that data is ready at 
the PET/CEM's port. These hardware topics are not wilhin the scope of this book. 


Programming the timers Both timers are used by the PET/CBM (although timer L's 
atch is ignored). Timer 2 is exclusively used with tape, to time the reading and writ- 
ing of bits. Timer 1 is used to time out the {EEE response (before setting ST) and 
also with tape, although not to such an extent as timer 2. (Both timers also contribute 
to RND with argument zero, but this is rather 4 marginal use. It does not apply to 
BASIC 1, which has the wrong addresses for the purpose). There is one more func 
tion, namely the timing of the screen-scroll delay in BASICs<4, which uses timer 1 in 


this WEY: Jo, PE  ;SETS HIGH PART OF TIMER 1 TO #FE, IGNCRING LOW PART, WHICH 
LbY #06; :19 SET AT #FF ALREADY ... 
DELAY STA E845 ;... AND ALSO (1) CLEARS Tl INTERRUPT FLAG, (11) STARTS TIMER 1 
Ls BIT ES4D : COUNT, IN ONE-SHOT MODE. T1 INTERRUPT IS DISABLED. 
BYC L ‘TEST IFA POR BIT 7 ON, {.E. Tl TIMED OUT 
DEY 


BNE DELAY ;PERFORM 8 LOOPS. AT EACH LOOP THE TIMER RYSTARTS. 


This wns dropped In BASIC 4, as it affects the IEEE bus; an ordinary nested set of 
loops replaced it. It illustrates these points about VIA timers: 

G) To toad @ value into a tiner, load the tow byte first, then the high byte. 
When this second step occurs, both bytes are transferred from the 'timer' to the ‘counter’ 
within the chip, and the countdown begins. 

Gi) Starting the timer cleors the timer's interrupt flag 

(iil} Reading the low register {not performed in the example) also clears the flag. 

Civ} Ti'a latch enables Ti's value to be read at any time. 
Note that the delay loop takes abaut 255*8*256 usecs = jy sccond or ao. [f LDA #x/ 
LDY #y/ JSR DELAY is used, variable pauses from 16 seconds to thausandtha of a sccond 
can be generated. 

BASIC ean be timed, provided the operations aren‘t slower than ebout 1/15th 
second: POKE 59460, 255:POKE59461,255:: PRINT PEEK (59160) + PREK(59461) - K 
shown the method, where K ia set to print 0, Any BASIC inserted between the colons 
wilt be timed by the system's clock and is therefore accurete to 1 microsecond, The 
value 'K' varies with spaces in the BASIC line. 


Programming the shift register We've seen (Chapter 9) how the CB2 pin of the user 
port can be uxed to generute tones. Now we can investigate the rationale for this. In 
BASIC, thls gives @ tone: POKE $9466,X: POKER $9467,16; POKE 59464,T: POKE 50483,0 
where X<>0 and X<>255. T controls the pitch. 59466 Ia the shift register. This {8 load- 
ed with a bit pattern, and the shi(t register Is enabled in free-running mode, euch bil 
shifting on T2 time-out, Finally, Umer 2 Is started, after Joading ita low byte with 4 
tlning paremeter. CBM OM doen not muke use of thin register. 


Proyramming interrupts Interrupts In T) and Té ace used in LEER handling and tnpe; 
CBE interrupts are alsa used with tape, CAM ROM does not tse lnterrupt sigsals fren 
CH2, the wiift register, CAL, of CA2. We'll louk at two exucples here; (ip Single ite. 
and (fi) using a timer toe control the keyboard. To program the fER, Agte that IhuT-0 
means thac all high blts dienhle the corresponding interrupts GE they are seth, Far ex: 
ample, LOA ATF/ aTA ER4U Cisnhies all seven interrupts. Qn the other ham, CEU7 1 
means that high dita enable Interrupts an LOA aU / ATA EAD enables Tis Interrupt, 
An [RQ wll now be geaerled when TL Umas out, Ch) Single isp fe.g. Superman's} 
enables T2'a interrupt, tarda off the screen interrupt (ty DEC Raa). altura [HQha vor" 
tor, and loads T2 with 46 decimal, This value Ia calculated fo (ime eat fient am Chae next 
machine-coda inatruction aterte. When Le doow, the interrupt awatls completion of th 
canmand, than jumps te the new [AQ address, which Mrst cally a tape routine fo piymet 
the Umera and eefeen Interrupt to narmal, before alenasemtliag Che lnatrurtion We 
can change thos rete of keyboured aceon, the internat clock, nel Ee curasr Thos rate fe 
animilor way, using Ttote generale reguint herropts, $f tha Interrupt procussicg 
aesquonea (a moves) ta RAM an referances lo EAL] tele beat (eth pwdad the aeseed: titer: 
rupt also tune). The time> ment vither be in free running acafo, ur reatarted with 
each inlerrupt, 


. 
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i 
CHAPTER 18: INDEX TO CAM BASIC ROMS ANO RAM STORAGE 
re 


PET/CBM MEMORY MAP 


ET 


ROM 


Tt Pages 0-15: 


ak $ ROM 
CBM anes 
sockets 
16 K 
cam 


RAM 
5 


22K 
CBM 
BASIC §& 
BASIC 1 
and 
BASIC 2 


PIAs, VIA, CRT 

controller (80 cols only) 

Screen RAM: 40, 0 ¥ 
80 celumns 





ws how the CBM's addressable memory of 64K bytes Is 

AM and ROM and fhurdware input/output. Each full-sized 

the blocks are therefore 0000 ~ OFFF. 1000 - 
chines with fess than 32 K have RAM space 
may not be possible or may require the same 
with hacdware modifications (i.c. ‘surgery’ 


The diagram sho 
partitioned between R 
block corresponds to 4K (4096) bytes: 
1FFF, and se on up ta FO00- FFFF. M 
ayailable, although increasing the RAM 
RAM slots to tuke larger capacity chips, | 
on the address tines). Spare ROM space is however Indicuted by spare sockets. 
These of course are often sccuplud by ‘toulkit'-type ROMs or EPROMs, stored software 
auch as word processors, Industrlal software in EPROM, and non-CRM devices of 
varlowa types ~ disks, video boards, : 

A derxeription of the BASIC ROMs would oo Incomplete without mention of the 
Sturn arens, buffers, fess and routines which BASIC Inevitably needs during ita 
aperation, With CHM egulpment, this merns pages wero to Une, stretching from 
lie imperlant zeru page ta the atart of BASIC storage in KAM, The KOM are very 
ninilur tg unch ather in many respects, of which absolute addreanen of ROM routines 
Is the major exception, The sequence on the following pages is based on BANI 4. 
‘The pulde Cnext page) showing how the working steraga aad ROMs are Iuid out 
shoul make the location of must routines fairly oaay. 
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rt 
PET/CBM MEMORY MAP: THE FIRST FOUR PAGES 


I 














BASIC § 186 COL) BASIC 2 BASIC 1 
USK jump address ~ : 

String pointers 
eral pointers ———_..____. Input buffer for BASIC 
BASIC pototers lines, direct commands, 
bi INPUT, GET 


09 





































Calculation wark area Aes BASIC 4 








—WASIC Tiage 
BASIC pointers 

“Varlables processing 

—“Galculation work area 





GETCHAR routine 
RND/ TIS int. vectors/ ST 
Keyboard/ screen/ [EER 


980 




















Tape pareametera and flags CHRGET routine 








Window pararetera Screan Line table 


1005 ASCIT couvérelon area 


Screen and file data 








Tape correction/ check rea 


























180 As BASIC 4 

1200 a = 
Input buffer for BASIC linea, Clock/ xeyboard buffer/ 
direst commands, INPYT, GET. —screen/ int. vectors 

—_Sereen line table __ oo. 

Yables: logical tiie #/ —_— ———As BASIC 4 Tables: logical file#/ 
device #/ sec. addr./ keybd. ——device #/ sec. addr? 

$280 prbutfoer. — ass a ee Sape-fiagas 


Casscttea buffer #1 


Cassette buffer #1 


pos Paap aS buffers ——— ——- YS 
and Cassette buffer #2 | 
—— ere Cassette buffer #2 


lhe, 2a: 








Most of BASIC 4 Je Identical to BASIC 2; BASIC 2 la fairly similar to BASIC 1. 
except far the Input buffer'a move from vere page to $0200, with tha: consequent 
changes In moat puinters. Major cifferences between BASIC 4 and BASIC gare (1) the 
sasnetie buffer for tepe #2 ia ne loner used aclely by tape opemitions, but ly the 
new disk commands too, and (il) bo elume HASIC 4 replaces the tablo of Bereen line 
polniuzs with acreen and keyboursd pardinetera, ABASIC 4 (40 col} and the 4O- column 
yaraion diffur In ROM £000 - EJF #, dealing with nereen and keybourd procesning. 
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BASIC2 (65) BASIC4a 


BASICY 


PAGE 0: RAM $0000 - SO0FF 


2 
$54 90 

$53B (91 

$5C 92 

$5D 93 

SSE 94 

$iF 95 
$6096 

$61 «(97 

$62 98 

$63 99 

964 «100 
$03.3 

$06 «6 

307. «7 

($08) 8-9 

$65 9101 
($66) 102-103 
$68-$70 


104-112 
{$71) 113-114 
{$73) 125-116 
$75-$79 

117-121 
($74) 122-123 
($7C) 124-125 
{$7E) 126-127 
($80} 328-129 
($82) 230-931 
($84) 32-133 
($86) 134-135 
($48) 136-137 
{3BA) 138-139 
($8C ) £40-141 
($GE) 142-149 
($90) 144-145 
($92) 146-147 
($94) 148-149 
($96) 150-151 


($98) 192-153 j 


($9A) 194-155 
$9C $56 
($9D) 157-258 
$9¥-$AZ 
159-162 
$A%- SAS 
144165 
$AG SAU 
146-171 
#$AC)172-173 


($AR) 174 175 
“BO SHS 

176 181 
sith 1H2 
470 184 
$b3 $E0 

154 189 


eee 
Nema = ar I airy eA, go 
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2 USR jump instruction (default prints ‘illegal quantity err 
or’), 0 holds @C=JMP; (S01) =jump address 
3 Offset pointer when scanning for end of statement or line 
4 Quotes marker. Is zero when not in quotes. 
5 Input buffer pointer/ number of subscripts of an array 
6 Default DIM flag/ array name initial/ AND. OR fleg 
7 Type of variable: #FFestring, #00=numeric 
a Type of numeric variable: #80-integer, #0+floating point 
9 Flag used in DATA/ LIST/ garbage callect/ memory 
$0A «10 Flag used for subscripts/ FN DEFinitions 
$OB ii Flag with INPUT=#0, CET=#40, REAL =#98 
soc 12 ATN sign/ comparison evaluation flag 
$0D 13 DS$ length in BASIC 4 only 
($0E) 14-15 DS$ pointersin BASIC 4 only 
$0D 13 Flag to suppress PRINT or PRINT# when negative 
SOE 814 sig 14 File number of current 1/O device (when 
non-zero suppresses [INPUT pronipt etc} 
$OF 15 Terminal width (unused ~ carried over From teletype} 
$100.16 Width of source (unused - carried over from teletypet 
($11) 17-18 | 2-byte integer address computed for GOTQ. SYS, GOSUB 
$i30 «18 index to next string pointer 
($14) 20-21 | Pointer to descriptor stack for string processing 
$16-$1E (Descriptor stack of three temporary string pointers of 
22-30 ‘the form length then 2-byte pointer 
($1E) 31-32 | Pointer e.g. for memory-move/ for string in memory 
' ($21) 33-34 |Pointer e.g. for number movements 
$23-$27 Intermediate product area for calculation 
35-39 
($28) 40-41 |} Pointer to start of program (usually $0401 = 1025} 
($2A) 42-43 | Pointer to start of variables/ end of program 
($2C) 43-45 | Pointer to start of arrays! end of variables 
($2E) 46-47 |Polnter to start of free RAM/ end of arrays 
{$30} 48-49 [Pointer to present lower limit of dynamic string storage 
($32) 50-51 | Utility string painter to reserve space for new string 
| €938) §2-53 | Top-of-memory pointer [e.g. $8000 on power-on with 32K) 
| ($36) 54-35 pourrent linenumber/ highbyte-#?F means direct mode 
($38) 56-57 |Previous linenumber 
($34) 58-59 | Pointer to statement for CONT 
($3C) 60-61 | Linenumber of current DATA line 
($38) 62-63 | Pointer to current DATA valye (starts at $0400) 
1($40) 64-65 |INPUT, READ, and GET vector to save CEHKGET 
($42) 66°67 |Current varisdie name. first character first 
| ($44) 68-69 ) Pointer to vurinble in RAM; points just after name 
($46) 70-7t | Hutds variuble aume for FOR,..NEXT/ WALT parameters && 
($49) 72-73 Save Y-register/ new operalor/ operater pointer cle 
$4A O74 jomee symbol check ; dils 0,1,2 are <,7.? 
{$48} 75-76 |Pointer to temporary storage in RAM for FN DEF, TAN. ac 
| $4D- $50 | Pointer to string. length, and gurbage collect conslant 
77-80 | 
$51-$53 [Jump vector for function evaluations, consisting of HC 
{ 42H) 1 ¢ WMP) Followed by ucithmetic Cunctlon address 
$54 $59 | Tunporary pulutera (e.g. ia memory move) plua numeral 
#4-49 {storage af internsalinte results ('Flanbng polat Ace'r eh) 
($5A) 90-91 | Numerle pointer e.g. In ASCH conversion, series aval’ 
| soe) 92-92) ‘Pulnlersa 26g, In LAT, seareh for hnenumber 
| $5- $63 iFlaating-polnt accumuleter #1 (most results of evafuations 
94 99 [are laft here}. Exponent, 4 mantissas, and siqn bytes 
sid 108 Serle uvaluatlon counter of sumber of iter ins peethos 
$45 (01 Overflow byle om nornuadiziiy floating, point acconmatifor tl 
[78s $68 {Flaating point accumutator #2 (used with FArc. #1 in eval 
102 107}ualion of pruducts, sums, differences, otc, EMMMMS 
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regramming the PET/CBi 
BASIC! BASIC2 (64) 


BE 190 S6C 108 Sign comparison between FPAccs: sU=equal, #FF opp. 
BF 191 36D 1oy Rounding byte for floating-point accumulator #1 
$C0) 192-193|($6E) 110-111|Cassette buffer length/ series eval'n/ VAL etc. pointer 
C2-$D 9194-217] $70 $87 102-135 BASIC's CHRGET routine which toads A with the next 
BASIC character (not space) and sets flags: 
C clear If ASCII numerat 6-9; Z set if end-of-sine or: 


ca 200 $76 198 CHROOT entry point joads A with current BASIC char- 
acter and sets flags as CHRGET does. 
DA-SDE $88-$8C RND number seed and subsequent values; always the 


}4-byte jiffy clock arranged most significant through 
141-143} least significant bytes 
194-145|]RQ RAM vector, usually £685/ E62E/ E455 
196-147}BRK RAM vector, usually 0000/ FOrT/ O478 
NMI RAM vector, usually --/C389/83FF to print tready* 
Status byte ST, from which ST is computed 
Which key pressed? (Interpretation may vary with 
\keyboard decoding). #FF=no key 
|snift key pressed? #0 if no, #1 if yes 


§12-$14 
$0219} $37-538 
$0218) $39-540 

none 
w2nc = «4524 
203 515 


($90) 
{ $92) 
($94) 148-189 
$96 150 
$97 15% 





ZiB-222 136-140' previous random number generated 
0200- $0202 $8D-$8F 


10204 516 $98 152 


Contents of E312 foc testing Stop key ete 





















$205) 517-5is]($99) 153-154) Low and nigh bytes of ‘correction clock' (stows TI) 
i209 = 321 $98 155 
W20A $22 $9Cc 156 Tape timing constant 
20H = 323 39D 157 Flag for LOAD or VERIFY: #OFLOAD, #1-VERIFY 
fo20D = 4.25 SOE 158 No. of characters currently stored in keyboard puffer 
O20E = $26 sor 159 Screen reverse flag: #0-normat, #12=reversed 
to2in = 547 $A0 160 IEEE output flag: #FF character awaiting output 
pO2Le = 542 SAL 161 Count of characters of line input from screen 
fo2ir «6543 «= «J $A2—s«162 J Not used sae 28 
po22006=— 544 $Aa 163° «| Cursor ‘row- fatso ‘$SF5/ $D8] ~ | 
$0221 545 $A4 164 Cursor column [alsa $E2/ icol | 
$0222 546 $A5 . g e-buffenfor-output (WPF means no character} 
$0223 547 $AG 166 Copy of keypress checked by interrupt so that a 
constant keypress registers once only. #¥F=no key 
$oz2z4 548 $A7 1167 Cursor on/off flag: *0-on, other. value = off ; 
$0225 549 $AB iT ountdown each interrupt for cursor flash 
$0226 © $30 $A 169 ;|Trve charecter at cursor’s position } 
$0227) S51 SAA 170___ | Cursor_in blink phase=41; otherwise =#9.) 
$0228 =6$52 SAB 171 End of tape input flag 
$0260 608 $AC 172 input from sereen (#3) or from ke bgard {3 fag } 
$0261 609 $AD 173 X-register gave in tape handling (saves cassette #} 
$0282 ©6610 SAE 174 Total number of open files (mux. 10) 
$0263 GIL $AF 1%5 Input device (default = K), keyboard) 
$0264 612 $60 136 Output device (default = #3, screen) 
$0265 613 $81 177 ‘!Tape charucter parity 
$2660 64 $82 178 Byte received flug 
$B3 179 Temporary save e.g. by DOS wedge 
$E9 233 $B4 130 Tape buffer leading chr. (e.4- #5:end of tape}/ MUM 
$0268) =—-686 $B5 181 MLM flag, counter/ (B4) points to file name for SAVE 
$86 182 
$0260 =—-620 $137 143 Serial bit counter 
$a 184 
$026F 623 shy 145 Cycle counter 
gsaztd 6624 SUA 1k6 Tape writs countdown 
($271) 625-626/(SHB) 187-188) Pointer (0-192 decinaty for use with tape operations 
$0273) 0 627 $hD 189 Counter for tapu writing ond tending 
$0274 62a SHE i990 Write byte/ arror flag on tape read 
sGLT% = 629 $F 19t Write utart bit/ read bit sequerice Prrope 
$0276 - $0277 $C0-$C1 | }Pans 1 read errora/ passé 2 read errors 
630-631 192-193 
$O27H G12 $c2 194 Caasetta read flnga: Orkcon! 1-14-count/ #402LOAD} 
as ond of tapaA merkar 
so279) = 633 sca 193 Counter af seconds bofora ispe writes checkaum 
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($ED}  224-223/($C4) 196-197/Pointer to screen RAM position of start of current line 
$E2 226 1$C6 198___|Position of curser along line : 
{$E3) 227-22R(($C7) 199-2001Start address for tape LOAD/ utility polnter 
($E5) .229-230!($C9) 201-202) End address for tape LOAD 
$E7- SEB $CB-SCC Constants for tape timing 
231-232 203-204 
$ES 233 $cD 208 Quote flag: #0=direct cursor, else control chrs. printed 
SEA o234.—Ss«ISCE.~=—s«206—Ss Tape read timer flag 
SER 235 $cr 207 End of tape read 
$EC 236 Bsa) 268 Read character errer 
SED 237 soi 209 (Length of file name; G=-no name 
SEF 239 $02 aro Current file number 
FO 240 $D3 211 Current secondary address OR'd e.g. with #60 
SFA 241 $04 212 Current device number: #0=keyboard, #1-2=tape, #3= 
screen, #4 typically printer, #8 typically disk drives 
$F2 242 $D5 213 }Right-hand of window (BASIC 4)/ length of current 
Jline (39 or 79) (BASIC<4 or 40-col. BASIC 4) 
($F3) 243-244/($D6) 214-215! Pointer to start of tape buffer #1 or #2 
$F5 245 $D8 216 |Sereen fine of cursor 
6 246 |$D9 217 Last key input/ buffer checksum/ temporary 1/O store 
{($F9) 249-250 |(SDA) 218-219) Pointer to start of file name 
SFB 251 spc 226 Number of keyboard inserts outstanding 
SFC 252 sDD 221 Write shift word/ read character in 
SFD 253 SDE 222 iNumber of blocks remaining tc read/ write 
$FE 254 $DF 223 Seriai word buffer “ 
$0229 $0241 1sE0-$F8 &3 column machines; Table of 25 high bytes of the 
553-577 274-248)RAM addresses of the start of screen lines. (A ROM 
table holds the corresponding low bytes). Lines which 
wrap around {i.e. are double length) are flagged. 
60 column machines: 
$E0-SE2 224-226 Top, bottom, left margins of window 
$E9 227 Maximum length of keyboard buffer 
$E4 228 Repeat flag: #0-on, #40-off 
$E5 229 Repeat countdown 
SE6 230 New key marker 
SET 231 Bell timing: #O0=off 
$E8 232 Counter for two {HOME} keys 
(SE9) 233-294 Séreen input indirect vector (SE11D) 
(tEB} 235-236 Screen output indirect vectur ($E26C) 
$ED-$F7 237-247 Unused 
$F8 248 Counter to speed TI by 6/5 
40207- $0208 SF9-$FA Cassette flags for #1 and #2 
519-520 243 259) 
(SF7) 247-2481¢$FB) 251-252: Polnter for MLM, start of tape address with 8 
-- (SPD) 253-254] Pointer for MLM, others 


PAGE 1 (THE STACK): RAM $0100-SOIFF 


SO0FF- $910F | $00P P- S0LFF 
$U10N- SOLAE $0100- $C19E 
$0149 slvr (50140 SIF F 
PAGE 2; RAM $0200-502FF 

| so200- sozie 


S0A-$5A $0200- $0250 


$9242-$0246B 
$924C - $0255 
$0256 $0263 


$025): SG254 
$0258 $0268 
$0765. $626E 





aR mS Er 


{Area for conversion of numerals into ASCIL string . 
format for printing 

Tope read error fog 

iStack as used by HASIC 


IMLM orea: holds, in sequence, stored velucs of the 
program counter high and low, tha proceauor sintus 
flagn, A,X,Y, the stack pointer, aid the IH vector, 
Input buffer. Length lv 00 characters maximum {plus 
null byte to terminate string) 

{Table of up to 10 fila numbers 

Pe of up to 10 corresponding device numbers 
Table of up to 10 corresponding secondary eddresses 


* 





coe a an RA en ene Ae SE NM erm me mT = 8 tennamarsetinge SAS 





ragramming the PET/CBM ~396- 15: CBM BASIC ROMs 

BASIC! BASIC2 (£4) BASIC4 

020F -$0216 $026F-$0278 $026F- Keyboard input buffer (interrupt driven}; 
527-536 623-632 623- length is variable in BASIC 4 

027A~$0339 $027A- $0339 Input and output buffer for cassette tape #% 
634-825 634-825 

O27A $027A Type of tape file 

$027H ) ($027B) Start address for load 

$027D} ($027D) End address for load 


‘AGE 3: RAM $0300-03FF 


0334,-$03F 9 $033A- $0 3F 9 Input and output buffer for cassette tape #2 
826-1037 826-1017 

O33A $0324 Type of tape file 

$0338) ($033B } Start address for load 

$034D) ($033D} End address for load 


$033A 826 DOS byte parameter in RECORD 
$033B B27 DOS drive number 
$033C $248 DOS drive number 


$033D $29 DOS length/ write flag 

S$Q33E 830 | -vit syntax checking flag 
$033F-$0340 831-832 Diskette 1D 

$0941 $33 tLength of BOS command string 
$0242-$0352 834-850 Buffer for filename 

$0353- $0380 831-896 Full DOS command string bufter 


40-column BASIC 4 only:- 


SO3E9 1001 Repcat key countdown 

SQJEA 1002 Delay between repeals 

S$O3EB 1003 Maximum size of keyboard buffer 
$03EC 1004 Bell timing: #-off 

$03ED 1005 Counter to speed TI by 6/5 
S03EE 1005 Repeat flag: #0-on, 4#40-off 


$03F0-SO3F9 1008-1017 Table of 80 bits to set tabs 


80-column BASIC 4 only:- 
$OJEE-$03F7 1006-10615 Tabie of 90 bits to set tabs 


($03FA) 1088-1019 USRCMO extension vector from MLM; set on power 
on to print .? in monitor. 


$03FC 1020 IEEE ‘timeout defeat’: when poked 
negative, ST is no longer set for 
timeout after .065 second's delay. 


PAGE 4: RAM $0400- SG4FF 


$0400 1020 $0600 1024 
$0401 = 1025 $0401 1025 


{Null byta at start of BASIC 

Start of BASIC storage (unless pointers changed from 
$0401). Sequence is 2 byte link address; 2-byte line- 
number; tokenised BASIC terminated by a null byte; 

and so on, until the end is marked by three consec- 

utlve null bytes. 
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av 


PET/CBM MEMORY MAP: GUIDE TO ROMS 


a 


APPROXIMATE CONTENTS { 








BASIC t BASIC 2 BASIC 4 
C000 


coo0 





B00 Keywords and operators with their addresses, and a 
table of error messages. Stack handling is here and 
includes routines to check space left on the stack and 
to search for tokens of GOSUB and FOR. The direct 
mode processing of commands and of BASIC lines, plus + 
the routines to clear variables and run programs, are | 
ail in this ROM: NEW, CLR, RUN. END, STOP, and 
CONT occur here, with with other system-like commands} 
including LIST, RESTORE, GOSUB, GOTO, RETURN, 
IF, ON and LET, and the input/output commands | 
PRINT, GET, INPUT, CMD, READ. Also LET is part | 
of this ROM; it ig a default keyword. [t checks variable 
types and evaluates expressions. 


| 

This ROM performs most of the complex processing | 
required by string and numeric variables. [It includes | 
arrays (‘subscripted variables'). the garbage collection | 
routine, gnd string-numeral interconversion routines { 
like STR$. {t processes sll Moating point accumulators 
and interconverts ASCII with numerals, integers and | 
} so on. Most mathematicel functions are calculated from | 
here, including PEEK, POKE, WAIT, SGN, ABS, INT, 
E EXP,RND, COS, SIN. 


‘| BASIC 4 only: processes the additional BASIC commands | 
used by CBM disks: DOPEN, APPEND, HEADER, and 

s0 on. Processing for DS and DS$ is partly here, and 

t 

{ 





partly in earlier ROMs. Actually. only about a half of 
thia ROM processes disk commands; the rest is taken 
from the previous ROM of older versions and from 
E00Off. of the older ROMs, and includes the MLM monitor. 
The first half of this slot (EQ00 - E7FF) is occupied by 
ROM; the remainder by a few [/O chips. Print routines, 
screen processing routines, keyboard and cursor cont- | 
rol and similar functions are carried out here. Note 4 
that 40-column BASIC 4 and 80-column differ in this | 
purt of ROM. Reset and IKQ also come here. | 
! All the tape processing ~- loading. saving, writing, and | 
reading - Is controlled by this ROM. The tape 1 
operating system is similar in all the ROMs, apart from | 
corrections mada to remove bugs from BASIC i. Tape | 
la not on IEKE device. Also the input/ ouput for JEEE 
in carrled gut from here; this inctudes OPEN, CLOSE, | 
¥VERIFY, LOAD aml SAVE and alag error meesiuies. | 
BASIC 1 has ne montlur, Dut (It dues have duycnontle 4 
routines (which only work if the user port fs apeciatly | 
wired up). BASIC 2 has most of Its MLM (monitor) here, 
The ‘kernel! Jump addresses ara here, In the top af 
iors near the 6502's NMI, Reset, and [RQ vectors. 


tee E 
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ASIC] BASIC2 BASIC4 
7000 §6$Co00 )6$B000 
D046 $C046 SB06S 
2074 $COT4 $b094 
cog2 $Co92 SBOB2 
cigu $C192 $B20b 
CZAC $C2AA $B322 
C2DA $C2Da $8150 
C2EL $C2DF $5357 
c371b 4$C31B $8393 
C32A $C32B = $83A0 
i387 $C355 $B3CD 
CIs9 $0357 SOCK 
C3IC S$CITA | FHIFU 
C38B $389 «6$BIFF 


S tables of addresses, keywords, and error messages. 
These are (i) Addresses-~ 1 of principal keywords, f.e. these 
which start a BASIC statement. The addresses are pushed 
on the stack and RTS executed (vin GETCHR) ta jump to 
them; hence the disptacemert by 1 from the true entry 
point. (ii) True addresses of numeric and string functions. 
(iii) Addresses - 1 of operators, with a byte to assign their 
hierarchy: the tadle corresponds to add, subtract, multiply, 
divide, power, and, or, negative, not, and comparison. The 
lattermost function evaluates <, =, and >, Their hierarchy 
values in hex are: 79,79.78.7B, 7F,50,46,7D,5A and 64. 

(iv) Keywords with the final character stored with bit Thigh. 
These include +,-,%,/ ete. which are converted lo tokens eas 
well as END, FOR, NEXT,... (v) Error messages, stored 
with the final byte zero a3 a terminator. 


The keywords in each ROM are different; BASIC 2 has GO, 
which is not present in BASIC1; BASIC 4 additionally has 
15 disk commands (including DIRECTORY). A list of each 
appears in a table in Chapter 2. The error messages 
are identical, except that BASIC i's BAD PATA becomes 
FILE DATA in subscquent ROMs. 


Check stack for ‘FOR', Called by NEXT and RETURN. If 

Z flag=0 on return from this, FOR has not deen found and 
° NEXT WITHOUT FOR results. Otherwise the loop variable 
is checked, Also eliminates FOR when GOSUB token is 
expected in the stack by RETURN. 


Open up space in memory. This coutine enables BASIC 
lines to be merged into BASIC. After checking that there 
is sufficient RAM, a memory move takes place up RAM. 
In BASIC 2/44$55)=Top of area to be moved te + 1 

($57)=Top of aren to be moved * | 

($5C }=Bottom of arca to be moved 

$1F =Temporary parameter. 
In BASIC 1 the parameters are: ($A7), (SAS). ($AE) and 
$71. On exit, all the pointers ure changed. 


Check space within stack. Tests whether twice the byte in 
the accumulator will fit the stack; if not, 70UT OF MEMORY 
is printed. The dottom of the atack allows 62 bytea for 
other purposes. ([.c. the whole stack is not used As a 
stack; some is treated as ordinary RAM). So, to fit 16 
bytes on the stack, LDA #5 then JSR to this routine tests 
the space, 


Check for overlap of BASIC strings and variables in RAM. 
On Input, A und Y hold the address high byte and low 
byte. If, on comparison with the atring pointer there {an‘t 
sufficlent roum In RAM, the Intermediate calculation Is 
atored and garbage Is collected. If there still tan’t room, 
POUT OF MEMORY EXROR Is printed. 

Print ‘OUT OF MEMORY ERROR‘ to the sereen - or; 

Print the error mexuige offset by X from ihe atart of the 
grrop messnye dubie. Then: : 

Rextors Kuybourd Input and sgreen output, reset stock and 
Nags, print “ERHOR", and If in program mode, "IN" with 
the Hnenumber, Then: 


Prints [Return] READY. (Return) and awalt BASIC jine or 
direct command, 


ETT TT far ie AE Ee NE IR CERT CREE, we Be ee URNA NRE A item ria hE 


eee Cee eh 
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aa 
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$C394 $C392 $8406 Await direct or program line from the keyboard. This calls 
C4SR/C46F/BBEG which puts one line into the input buffer, 
and on [return{ puts o zero terminating byte at the end of 
its Input. After this, the initial character ig read by CHR- 
GET. If this returns carry clear, the initial character was 
numeric, and the following routine is branched to; otherwise 
it's treated as a direct mode command, and is tokenised and 
run by C48D then C6E9/C495 then C6FT/B4FB then B7TC. 


$C3AC $C3AB $B41F Tokenise BASIC program line. if the linenumber exists. 

$C3FD $C3FD $8470 replace it; if it Is new, insert the line into BASIC in RAM, 
Note that the length of the line is stored in $5C /$05/$05. 
If the line exists. it is erased by a memory move routine at 
C3EF/C3EE/B462 before dropping through to the line insert- 
jon routine. All the variables are erased by CLR and BASIC 
is rechained (so variable values are lost on editing). Then 
the previous major routine is called again. 


$0430 $C339 SB4AD Reset BASIC execution to start; clear; and chain. This is 
also called by LOAD when not in program mode. 


$Ca33  $C442 $BKB6 Rechain BASIC program in memory. This searches for 0 
bytes marking end-of-line, then recalculates the link add- 
resses, Lines longer than 255 cause this routine to hang. 
BASIC 1 has 6 different implementation from the other 
BASICs and is used by the keyboard entry routine. 


$Caea $Ca6F $84E2 Input keyboard line into buffer. BASIC I's Input buffer 
starts at $0A; subsequent BASICs start at $0200. Single 
characters are input fron a ‘device’ which is usually the 
keyboard, and stored in consecutive locations in the buffer, 
until [return] is pressed. Then, 4 null terminating byte is 
put into the end of the string and RTS is called. BASIC 4 
tests whether the line exceeds 80 characlers, and stops with 
Istring too long error if so. Earlier BASICS use a little 
routine to fetch a character, based on FFCF,. which appears 
to suppress output if CHR$(15) is read in, This is dropped 
in BASIC 4. 


$Ck79 «$C481 Singie character input routine. 


gcasD $C495 $BAFB Tokenise the Input buffer. The buffer is processed until 4 
zero byte is found, each recognised keyword being con- 
verted into a single byte (with bit 7 set high}. ? and “* are 
checked. BASIC 4 uses ($1F) a6 a pointer to the tutle of 
keywords; this tuble is now too long to be spanned by 6 
single register's offset. This is the routine which can be 
fooled by eN, f[O,nE and so on. 


$C522 $C52C $B85A3 Search BASIC for a finenumber. In BASIC 4, ($11) holds 
the linenumber, low byte firat aa usual, On exit, carry bit 
clear means that the line was not found. If it exists. ($5C) 
polita to it, The Jocation pointed to Is the atart of the link 
addresa, le. one byte bayond the @ end-of-ling murker, 
BASIC. 2 is identlerl: UASIC 1 uses ($08) and (SAE). 


$C55) $C55B $8502 Perform NEW, This hus a syntax check lo. disallow NEW 
followed by anything ater than : or zera byte. ft reties on 
the slart-of BASIC polntera; putting zero bytun ita the 
sturt of BASIC. ond the next byte, then storing stort + 2 
info and of HASIC, Next GETCUR th loaded with stant -of- 
BASIC 1. Then the fallowing i4 executed: 

$CS6A $C577 $B5EE Perform CLR, Gike NEW, Chit his w xylan check. lis selon 
fasuntiony bs to ret all the varlables' pointers to dceobead elas 
witht (he pointer lo the end of WASIC, xo They are effectively 
erased, The slack Ik olae reset. And 1 activity isalsorted. 


* 
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$CS9A SC5AT $B622 Reset GETCHR to start of program. Adds #FFFF to ($29) 
and stores the result in ($77), {Compare this with RESTORE 
to see different programming styles). 


§C5Ae $C585 $8630 Perform LIST. Full check for parameters, including -. 

$C5C9 $C5D6 SBG51i List program with no parameter checks, ($11) holds the 
high line number and defaults to #FFFF with L(ST or LISTn-. 
($5C) points to the low linenumber; #0401 is its lowest value. 

$C5D5 $C5E2 $BS65D List one tine of BASIC, i.e. number then text. 

$CG2B $C63A $B6B5 Converis a token in A (i.e. #$80+) into keyword. 


$C649 §C65a8 $86DE Perform FOR. This sets up a block of data on the stack. 
It assigns the toop variable valuc, then checks the stack 
for FOR and for 18 bytes of space. Its scans for the end of 
the FOR statement, and pushes 18 bytes onto the stack: 

$C664 $C673 S$B6F9 (i) Pointer to following statement, (ii) Current linenumber, 
Gii) Floating-point value of higher limit, (iv) Value of STEP 
plus its sign byte, (v) loop varinble name, (vi) FOR token. 

$C692 $C6AL $8727 This routine processes STEP by assuming | and overwriting 
this with the true value if a STEP token (#A9) is found. 


$C6B5 $C6C8 $874A BASIC warm start, This is the controlling loop which runs 
BASIC statements. It tests the Stop key, updates the CONT 
pointer (unless in direct mode) and tests for colons or for 
end-of-line null bytes between statements, 

SC6CF $C6D4 S$B7SF This routine exits if an end-of-programQis found (so that 
END isn‘t needed) and otherwise processes a new line, by 
incrementing the CHRGET address to point to the start of 
the next line. 

$C6E9 $C6F7 $B77C BASIC start with CHRGET pointing to BASIC text (not link 
address). The above routine drops through to here, where 
GETCHR gets the next BASIC character, the start of a 
statement, into A, then executes it with the following sub~ 
routine, and luops back to the warm start entry point where 
CHRGET points to a link address. 


$C6F2 $C700 $8785 Perform a BASIC keyword. This routine (i} Returnga with 
nothing done if a colon is found; (ii) Assumea 'LET' by 
default If a tuken is not the first character found; (ii) 
Checks that tokens (i.e. byte with high bit set, therefore 
with value #$80 + ) are within the runge of the token table. 
{If BASIC 4 disk commands are 'run' on BASIC 2, for 
example, the tokens will be unrecognised}. (iv) Lastly, the 
keyword’a address Is pushed on the stack. These two bytes 
gre taken from the table at the start of BASIC; they're 
found by doubling the value (token ~ #540) and using this 
as an offset, Note thet BASIC 2 has a patch to test for GO. 
it checks that GO ix followed by TO, then performs GOTO. 
The actual execution is performed by Jumping to GETCHR, 
go that the accumulator holds the next chnracter of HASIC 
and aise the address of FOR or RESTORE or LET or whieh- 
ever it may be ia made the destination when RTS la reached 
at the end of GETCHR. 

$C70D $C730 $B7B7 Perform RESTORE, Sets the DATA pointer to utart-of- 
ASIC, os this appears in the pointers, minua i. In BASICd 
($3E) holds ($28) - £; in BASIC 1, ($04) becomes ($7A)>~ 1. 

$C71C $C73F $87C68 Perform STOP, ENO and bresk In program, [f the earry Nak 
is set (for example, when SFFET testa the atop key und finds 
it pressed) STOP Ja performsal, if % la alsa net. If carry lt 
gloat, END i performed, Both ruuthies ave iifermation for 
CONT (pointer ta HASIC, Unenumber) untesn li diruct modes 
STOP printa BREAK [tion, whiln SND wklpa this te print 
only READY, The stup key performs STOP, and an ond-uf- 
program terminating rero calin END. © 
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$C7R85 $C76B $B7EE Perform CONT. This (i} Rejects CONT if it is followed by 
something other than an end of statement indication, (ii) 
Prints ?CAN'T CONTINUE ERROR if the highbyte of the 
pointer is #0; it's set to this on a syntax error. And 
(iii) The pointer into BASIC and the then-current BASIC 
linenumber are restored, and the program continues. 


$C775 $C785 $8808 Perform RUN. This has two branches, RUN and RUN n, 
where n is a lincnumber. 

$C567 $C572 $B5E9 RUN rescts CHRGET to the start of BASIC, then CLRs 
variables and stuck and runs. 

SCTITA $C7T8A $820D RUN n CLRs variables end stack then ealia 'GOTO'. 


$C780 $C790 $B813 Perform GOSUB. This tests the stack for space to pusn 6 
bytes; if this docsn't elicit 70UT OF MEMORY ERROR, the 
following 5 bytes are pushed on the stack: (i) Contents of 
CHRGET, Gi) Current linenumber, (iii) GOSUB token (#8D}, 
Then it calls GOTO, which changes CHRGET according to 
the location of GOSUB’s tinenumber, and finally warm starts 
BASIC from its new position. The data on the stack is used 
by RETURN. 


$C79D $C7AD $B830 Perform GOTO. There are three parts to this routine: the 
first fetches the tinenumber following GOTO, and stored it 
in ($11} or ($08) in BASIC 1. Then, this linenumber is 
sought in the program: to save time with long programs, 
the following linenumber is compared with the sought one 
and the starting point of the search depends on the result 
of comparing the high bytes of these lines. Finally, the 
routine to search BASIC for a linenumber jooks for the tine 
and if it's found loads the pointer (less 1) into CHRGET. 
Fo clarify the operation, consider this program line: 
10060 GOTO 12090, which may be part of a very tong pro- 
gram. 10000=39°256 + 16, so the current linenumber is 
stored as the 2 bytes 0A and 27. 12000-46256 + 224, which 
is stored as EG and 2H. The highbytes are compared, and 
since 2E exceeds 27 only lines after 10000 are serached. 
On the other hand, 10000 GOTO 10001 searches BASIC from 
the start. 


SCICA $C7DA $885D Perform RETURN. Thia checks for GOSUB ou the stack and 
recovers the subroutine's details, or prints ?7RETURN 
WITHOUT GOSUB ERROR. (1) The syntax is checked, (ii) 
The atack is searched (bypassing FOR'‘s variabie polnter 
processing) , (iii) 1f A doesn't hold the GOSUB toxen (#9D) 
the error message is printed, (Iv) The original BASIC line- 
number and pointer are reconatructed, (v) The next state- 
ment is found, as an offset in Y, (vi) CHRGET's address is 
set, eo the next statement will executa. 


$C7D8 $C7ES $868 Printy 7RETURN WITHOUT GOSUB ERROR. 
$C7DD «SCTER SHHGE Prints UNDEF) STATEMENT ERROR. 
SCI9A S$CTFO $BFO0) Prints 7SYNTAX ERROR, 


$C7FO $C800 $6863 Performs DATA. This routine I4 shared with the end of 
GOSUE: it’s the part which looks for and continues with 
the neat statement, so Lnat DATA 1,2,4; PHINT X iynoros 
the DATA, but curries on at the print statement. 


$CIFE $CBOE $B889t Search for next BASIC statement. Looka for : or null byte, 
$C801 $811 $8994 Search for neat BASIC Ine, Looks for null byte, marklag 
the end of the ling. In alther case, ou return the Y register 
holda the dliplecemant from CHKGET'S addeesa, which is 
($77) or ($C) In BASIC 1. An Interchange routlie bt used 
to chaura that a colon within quotes [a not regarded aa an 
end-of-sintement indication, 
‘ : 
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iCB33 


sCB43 


5CB63 


$690 


$CBBe 


$c8B8C 
$C8CE 
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scape 
sC91C 


$CO7F 
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$Caay 


$C853 


$Ca73 


$CB8AD 


$C8C2 


scscc 
$CaDE 
$C937 
SCBEF 
$C928 


$C9ee 


$B8C6 


$8806 


$B8F6 


$BS30 


$6945 


SBO4F 
$H961 
SHORA 
$B9T2 
SBIAB 


$BAEa 
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Perform IF. This routine evaluates the expression following 
1F, and checks that the expression is followed either by 
GOTO (#89) or THEN (4A7), Assuming this to be OK, the 
next step is to load the accumulator with the exponent of 
floating point accumulator #1, in which the result of the 
evaluation was deposited. When a result is evaluated as 
zero, the exponent is set 0, and because of the importance 
of this special case, it is sufficient to test this single byte 
when finding if a result was 0. 

At this point the routine branches: a resuit of 0 means 
‘false’. In this case the next line is found, and an uncon- 
ditional branch rejoins DATA at the point where CHRGOET 
is incremented by the offset to the next line. This is the 
same routine used to perform REM, 


If the result was non-zero, this is regarded as ‘true’, and 
the next statement is executed using the keyword processing 
routine - unless a numeral follows, when ‘GOTO' is calted. 


Perform ON. (i) Cheeks variable type and evaluates it, 
Gi) tests for either GOSUB or GOTO, (iii) repetitively 
decrements the variable value in $12 (or $84 in BASIC 1), 
and works through the list of commas, until the value is 
reduced ta zero. When this finally happens the token is 
recovered from the stack and the appropriate command 
carried out by entry into the routine which executes BASIC 
statements. (If the location never becomes zero, the next 
statement is performed by default). 


Fetch integer {usually linenumber) from BASIC, This uses 
shifts, rotations, and adds to multiply consecutive ASCII 
digits by 10, add the next, and so an until a non-numeric 
character is encountered. On entry. A holds the value read 
by GETCHR. If it ian't numeric, there ig an immediate 
retuen and the number is 0. Note that validation is not 
complete; this is why ‘GOTO 100xxx' Is syntactically OK. 
To use this routine, point ($77) in GETCUR tec the start of 
the number. Then JSR 0070/ JSR BSK6 reads the number 
Into ($11) and leaves ($77) pointing at the firat non-numeric 
character. BASIC I's GETCUR is ($C9), and numeral ($08). 


Perform LET. ‘lhere are three parts to this routine: 

(i) The variable (X say in X=5) is searched for in RAM, 
and set up If it doesn't yet exist. (ii)'=’ is ehecked for 
(its token Is 482) and the following exprossion or giring 
evaluated. (li) Ploating-point accumulator is inoved into 
RAM or pointers sre set to the atring. depending on tht 
type of variable. This completes the assigning process. 
These are the entry points fer the assigninent; see VARPTR 
for an illustration of assignment. 

Assigns floating-point numbers 

Assigns integers 

Axssigns sicinga, except: 

Ansigua TIS (e.g. Th$ 7125458") 

Adds ASCH digit, pointed ls by (SIF),Y, to the present 
contents of flonting-point accumulator Wi, (Used by the 
previous routing with TIS), 


Perform PRINT#. This routine has two opeades only; tie 
firat calls CMD, which iy why the syntax of CM) nad that of 
PRINTS are identleal. The second jumps to the end of the 
routine which performs INPUT#, ‘The part of this coutine 
which It executes aborts the file used by CMD and sets 

the ‘current devices! lo zera. That is,lucdtions #14, ann, and 
40J in BASICR 4,2, and trenpeetively are made zere, 


. 
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BASIC 
$C965 $C991 
$0999 $C9A5 
SCOSF $CSAB 
SC9AB SCOBB 
SC9AF SCOBC 
SC9A3. SCOAF 
SCIAT $CIB3 
$SCSBA $C9C7 
$C9D8 = $COE2 
$C999 $CIAS 
$CA27 $CATC 
$CA44 SCAIS 
aS $CAID 
$CAS4 =SCA4D 
$CA47 = $CAMD 
$CAT7 $CAF 
SCARF $CATD 


$BAA2 


$BAAS 


$SBABS 
SBAB9 
SBAAC 
$BAB0 
$BAC4 
SBADF 
$BAA2 


$BB1D 


SBBSA 


SBB3E 
$BR41 
$BB44 


$BB4C 


$0874 
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Perform CMD. CMD is identical to PRINT#, except that the 
output device is left as an output device, not cancelled. 
Thus, future output, even with PRINT, gous to the same 
device. This is roughly what happens, at any rate, CMD 
evaluates its parameter (single byte only) and stores it in 
$62. ($B4 with BASIC 1}. The comma is checked for if the 
statement hasn't ended. The output device is set by FFC9 
and PRINT performed. 


Part of a loop which PRINT uaes to print a string from 
memory, then continue with punctuation of PRINT... 


Perform PRINT. This is the main entry point to PRINT from 
BASIC. The flowchart of PRINT in Chapter 5 shows what 

it does. On exit the buffer is reset: $0200 halds #0, X holds 
#*F, Y hoids #1. (BASIC 1's duffer is different - starts at 
$04. Note that BASIC tprocessing is rather different from 
later BASICs. HASIC 4 is closely similar to BASIC 2, except 
that the CMD file is $10, not SOE, and linefeed is not 
automatic after carriage return). 

Test for comms, branch if found. 

Test for semi-colon, branch if found. 

Test for TAB(, branch if found. 

Test for SPC(, branch if found. 

Print numeral) (after converting to ASCII string). 

Print CRLF or CR. 

Print string. 


Print string from memory. From this entry point, if the 
accumulator A holds the low byte and Y holds the high 
byte of an address, this routine prints eonsecutive char- 
acters from that location upward until a zero terminator ig 
found. BASIC 4 is reported to insert zero bytes; it may be 
necessary to write a routine with FFD2 on the lines of 

this next routine: 


Print a screen format character. BASIC 1 prints cursor right; 
the others print efther cursor right {te screen) or space 
(when some output file exista). BIT {ns used to separate the 
alternatives. 

Print space 

Print cursor right 

Print ? for error messages - also slipped in. 


Print error messages for GET, INPUT, and READ. On entry 
to this routine, a zero pege Mag (location $08 or, in BASIC1, 
$62) holds #0 to denote INPUT, #$40 for GET, and #$9% for 
READ. The routine sepurutes these out; READ and GET 

both generate 2SYNTAX ERROR and exit to direet mace, 
INPUT splita according to whethor a file is apen or not; if 
not, 7REVO FROM STAR is printed and GETCHR loaded 
with the previous Hnenumber's pointer again, (f a file Is 
open, 7FILE DATA ERROR (or BAD DATA in BASIC 1) 
termites the progrian, 


Perform GET and CET#. CHT fs based around FFEA, 1s 
might be expected. Its additions inclurte: (i) Testing for 
direet mode, (I) where ‘# extats, inputtiag the file number, 
checking the comms and setting the device for input, (Hib) 
getUng the input buffer for one character only wlth mult 
bytes, (iv) GETLing the charmeter and assivning tote ite 
vorlable, and finally, where an input file wad used, 
restoring (he default devices of sereen and keybourd, 

Note Jhat A is loaded with #40 before the GRY? INFL SREAD 
routine prucesied the dingle inpud charmeter, Slated in $01), 
iis keeps the three procmaen distinct whe necessary. 
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$CRB9 
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$8BBE 


$BBF5 


$BCO2 


$BCO9 
$BCOB 
sBcéD 
SBCES 
$BCB4 
SBCDA 


$BCPT 


$BDi9 
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Perform INPUT#. INPUT# relies heavily on INPUT; it adds 
only input of the file number and a check for the presence 
of a comma, plus the turning on and turning off of the 
device on either side of INPUT. 


Perform INPUT. If a quotation mark is found after INPUT, 
by CMP #$22, the string within quotes is pointed to and 
printed - usually to the screen. Direct mode INPUTs are 
rejected. Now the following routine is called, which, on 
carriage return, completes input of a line to the buffer, 
using in fact the same subroutine as BASIC in direct mode. 
There is a test for ST. if this is 3 (BASIC 4) or 2 in the 
others. the command is aborted and the next BASIC state- 
ment carried out. The scanning and assignment of the 
parsed input buffer is carried out in the GET/INPUT/READ 
routines, where INPUT is signalled by #0 in SOB. Note that 
the INPUT crash, on carriage return, is deliberately 
programmed in to go to END, 


Print 7 prompt and put input inte buffer, This is the 
routine which INPUT uses to get duta to the buffer. All 
datu is transferred on carriage return, including commas 
and colons, which are only distinguished as separators by 
the parsing routine after this one. User-defined INPUTS 
can use this routine, omitting the query if preferred, to 
input and format data in other ways than CRM's. 


Perform READ. GET and INPUT share this routine, but 
ere distinguished when necessary by the flag in S0B, which 
contains #93 with READ, The object of tnese routines is to 
scan the input buffer or DATA statements, assigning 
variables tn each syntactically correct chunk of data, and 
signalling mismatches ond other errors. 

INPUT entry point, 

GET entry point {preceded by LDA #$40). 

Assign string to string variable, 

Assign numeral to numeric yariubic. 

Scan program for DATA statements; used by READ. 
Checks whether pointer is at end of buffer, fe. for zero 
byte. If this Isn't found it prints "EXTRA IGNORED - 
unless there is an active file, in which case no warning 

Is printed, 


EXTRA IGNORED crif and 7REDO FROM START eclf 
text messages (with null byte terminator). 


Perform NEXT. NEXT curries out this sequence of oper- 
ations: (i) If NEXT ig alone, (346) beeemes #0000; if not, 
the variable fullowing NEXT 1¢ sought in memory, and A 
returna set to the low byte of its pomter, ¥ to the high 
byte; these aro put ln (£46). The stuck is searched; no 
FOR. o¢ no matching FOR, gives 7NEXT wIrtlour Git 
ERROR. Gh) The eurrent value of the loop variable iv added 
to the atep, amd the resull mieved up within RAM. This 
requires baveral poiiters ta ter et, e.g fulo variable 
storage in RAM, Cit) Tins compari routine is celled, whieh 
sels A depending an the result, (iv) {fF the toop ia new 
flatshed, another route defetes the stack cutey and checks 
for » comme. If one ts found, MUX LT ds enterod vwaraln. fv} 

If the loop isn't finished. CHROLE aad the prevlaualy 
current heenumber are oadecd Oni (rey ite with RELTURNY 
and (he BASIC warm start reutine ceutitiues Che prog cum. 


. 


NTT ETT TE a ee ME EIR ER Pe RNR eT ETE Fema =? 


Peat 


"Dees seamen aarti: 


$CCAS 


$CCA? 
$CCAS 


$CCB8 


$CCC3 
$CCD2 


$CCFi 
$CDIA 


$CDT2 


sCDoD 


$C UBC 
SCS 
SCH OLS 
VOLOE 
SCELI 

SCEIC 
SCELt 


Tem re ole ae 


$ccaB 


$CCBE 
$cC90 


$CCSF 


SCCAA 
$CChd 


sccba 
scD21 


$<N59 


$CDA4 


SCDAI 
SCDEL 
sem? 
FCPS 
$CUFK 
SChO3 
CUA 
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$Bba7 
$BDa9 


$BD98 


SBDA3 
$HDBZ 


SBDDi 
SBELA 


SEGA 


SBE 





SHAG 
SULE? 
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Input and evaluate a numeric expression with check for 
type mismatch. This calls 2 subroutine - a little further in 
ROM - which evaluates any BASIC expression, whether 
string or numeric, Numerals are Seft in floating-point 
accumulator #1, and $07 iy loaded with a flag: #FF for a 
string expression, #0 if it was numeric. {The flag is $SE 
for BASIC 1). Checking for type mismatch is done by the 
next routine: 


Checks numeral was input. 

Checks string was input. These routines interlock; the 
carry flag determines which category of variadle will cause 
7TYPE MISMATCH ERROR. Note the use of BIT $33 to give 
an entry point which sets carry. (SEC = #538). 


Input and evaluate any expression. This elaborate routine 
(500 bytes or so excluding other subroutines) parses any 
string or numeric expression, checking for syntax errers, 
and on exit leaves the type of expression Mag ($07, or 

$5E in BASIC 1) set to #FF for a string, #0 for numeral. 

lf numeric, the result is left in floating point accumulator #1, 
From here it can be processed further; JSR CF93 converts it 
to an ASCII string at the low end of the stack, and ISR 
BBLD prints this out, for example. (These are BASIC 4 ROM 
addresses), [f the result is a string, on exit from this 
routine A holds the length, as do $5E and $C8; and the 
pointer is stored in ($60) and (SC8). BASIC 1's locations are 
$CC and ($CD9, and $80 and ($B1) respectively. 

Note that this routine is net an INPUT routine, but takes 
a BASIC expression from RAM; before calling it, CHRGET 
must point to its starting byte. It enables complex express- 
ions like 24*VAL("1. 23"+X$)"5*(A=NOT B)} to be evaluated, 
In the process, a lot of the stack and many zero page fags 
are used. All Microsoft BASICs have a routine of this type. 
Parsing is by operator precedence in the case ef numeric 
expressions; as the expression is scanned, an operator of 
greater hierarchical value is pushed on the stack, with the 
evaluated result from accumulator #1, An operator jower in 
the hierarchy pops the stuck result into accumulator #2, 
which ia then combined with accumulator #1. The routine is 
recursive. Unexpectud OUT OF MEMORY ERROR messages 
may appear with rather complicated expressions. because of 
the {ntermedlate results on the stack; simplifying into short 
sub-expressions may cure this. 

Push accumulator onto stack and recursively run routine. 
Test for >2< and store their combined code in $4A ($IC with 
BASIC 1). 

Process other operators 

Puis FPAcc. #1 on the stack and performs mathematical 
Gperution determined by offset Y and tuble of addresses, 
Pop sluck into FPAcc. #2; louds A with exponent. 


Evaluation routine. ‘This looks for ASCIO namerul strings, 
w.g. 124, varinbles, pl, . 7 ¢ "NOT, FN, arithmetic 
functious, egg, SGN, ABS, and expressions in purenthases . 
VWioas 5 byle flualing point mune. 

Cheek parentheses and evaluate expression wihin them, 
"SYNTAX ERO Ff CHRGET docen't point tu). 

ONY NTAX ERROI TE CHRGET doesn't point to 

SYNTAX ERROf if CARGET docantt palnt ta .. 

"SYNTAA LHROI and return ta READY, 

SYNTAX ERROK Uf CIUUGET docun’) poli fo a byte identiont 
te That in A, Uf dt dees, A returm with Uba next character, 


Le net I mR a A a IRR pre AW UA ma am ene a rl = 


a 
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CE28 


iCES8 
iCE6S 


iCEBD 
iCEBA 


iCE79 
iCED6 
iCED9 


iCFO6 


ICFOB 
BCFLE 


§CF71 


$CF7B «$CF6D «6$C128 


SCECF 


$CE2E 


$CE4) 
$CE82 


$CE60 
$CETD 


$CEB89 


$CEC8 
$CECB 


$CEFS& 


$CEFD 
$SCF1LO 


$CF63 
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BASIC4 


$BECC Evaluate a variable. This first uses the routine to search 
for a variable in RAM, returning with A holding tha low 
byte and Y the high byte of its peinter. Strings are not 
processed, except for T1$ and DS$ in BASIC 4 but all 
numeric variables - integer. flonting-point, TI, ST and, in 
BASIC 4, DS - are evaluated and the result is stored in 
floating-point accumulator #1. 


Read clock (TI$) and set up string hotding result. 

Read DS$ and set up string holding result. 

Evaluate integer variable. Result in FPAcc. #1. 

Evaluate floating-point variable, not T?, ST. or DS. Note 
that (i) BASIC 1 uses a set of patches in E19B-ELDF which 
are moved to be in line with the main code in BASIC 2. 
(li) BASIC 4 has o slightly different arrangement, due to the 
introduction of DS and DS%. 

Evuluate T!. Result in FPAcc. #1. 

Evaluate ST. Result in FPAcc.&#l. 

Evaluate DS. Result in FPAcc. 41. 


SBFAD 
$BFCOo 
SBFDS 
$C050 


S$BFF3 
$CO1l7 
$co24 


$coq7T 


$CO86 
$C0a9 


Process arithmetic functions. 


Perform OR. 

Perform AND. These two binary operations are written as 
one routine: a flag holds #FF for OR, #0 for AND. See 
Chapter 5 for the rationale. The flag is location $05, or, 
in BASIC 1, $5C. Each of the two arguments is converted 
from floating-point to integer form, with an error message 
if the range is wrong. Intermediate results are stored in 
the zero page. The result is left in FPAce. #1. 


Perform comparisons. This routine begins by testing that 
the two items do in fact metch in type. It separates into 
two branches depending on whether numerals or strings 
are to be compared. 

Numeric comparison, and:- 

String comparison. 

Numbers are compared with another subroutine (DB2D/ 
DB67/CD91) after first modifying FPucc. #1 to include the 
sign bit in the mantissa. 

The string conpurison function works like this:~ 

The first string’s parameters are $3Eslengti, (95E ) =pointer; 
the second string has its length put in A, and its pointers 
in ($69), (BASIC i is different - BO and (B11) and (BB} 
ate its equivalents). Fhe X register holds one of three 
values on exit: X70 acana the strings are equal, 

X21 means the first is ‘greater than’ the sccond, and 
X<255 means the second is ‘greater than’ the first. 

The accumulatur holds only #0 or #255 on exit; this vartes 
with the contents of the compariaon evaluation flag, 


Perform DIM. Thia routine caija the next rouline, which 
searches foe a vurisbie in memory and sets it up ff it ian't 
found. So for examples DIM ASf44) seta up the varinble 
AS(44) Sn memory; and in the process it yeneentess tha 
entire array from vlementa ASLO) through tp AS(44), If the 
atntement bun not ended, the routing loops repetitively, 
cheekIng for a comma, and setting up the next array, 


Search for varlatte and set it up If net found, The Firat 
hulf of thix rovline validates tne varinble'a nome; the 
fending character must be alphuhetic, (he tixt may be that 
or numeric; a loop rejesté further alphanumerica; oad the 
varteble typa flag in $07 bn wat to AFR IPOS |e found, ane 
40 olborwhse; and the numeral Mug tr $0H Becomes #20 Hf a 
‘4! in found. $0A Indleatus a function, A 'C canes another 


$COB6 


$CORB 
$COCE 


$Ct2t 


ee ee EI ese HEE PN op rec eRe II ir ee fare ar 2 


od 


AS ae iP on ae 
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SCFD7 S$CFC9 $C187 
$D00S S$CFF7 §$C1B6 
$DO0OF sDoot $cica 
$b08s S$D078 $C2C8 
$D099 s$D089 $C2D9 
$0090 $D08D $C2DD 
$D0B9 SDOAC $€2FC 
$D100 S$DOF3) $C343 
$D149 «=$MI3C $C38C 
$D135 S$DI28 $C37A 
$D1i2D $b120 $CI70 
$D130 «$N123) $0373 
SDIFQ $DIKT = $C436 
$D2330 $p224 $C4aTT 
$P135  $DI28 = $CI7TB 
$0264 $0259 $C4As 


ee RU eee 


oat in by ea 
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the nome is stored in ($42), with its initial character in $42. 
BASIC 1, naturally, is different - it uses ($94). These ate 
stored with their high bits set according to the type of 
variadle: sce Chapter 2 far the four types. So much for 
the first part of this routine. The second actually looks for 
the neme in RAM. All the variabics are stored together after 
BASIC and before the arrsys; moreover they each occupy 4 
tatal of 7 bytes. So a loop simply compares consecutive 
variables until the sought one is found. {ff in fact it doesn't 
exist, the ROM routine 'Creute a new BAS(C variable’ is 
branched to. 


Check A holds alphabetic ASCII character. 
is set to 1 if A hoids ASCII A-2, 


Create a new BASIC variable. Sets up a new simple (not 
array) vuriable in RAM after the present variables. 1f any 
arrays are present, they have to be moved 7 bytes up in 
RAM to accommodate the variable. The array pointers need 
to be changed. and BASIC 4 string-into-pointers also need 
to be updated. This can take a second or two. On exit, 
($5C} points to the start of the variable, i.e. the first 
character of its mame; ($44) points two bytes forward of 
this, to the variable's value or pointers if it's a string. 
All its bytes are set to zero. Tl and ST, and BS with BASIC 
4, are checked for and give ?SYNTAX ERROR if they've 
been used on the left of an exprension. The same is true of 
DS$. TIi$ returns with a dummy value (null string). 


Aliocates space for array pointers. This adds #5 to twice 
the number of dimensions of an array, and in turn adds this 
result to a pointer. This makes room for the housekeeping of 
an array, not for the actual data. 


The carry flag 


Holds -32768,0005 a3 a $ byte floating-point numeral. 


Input and evaluate expression as a positive integer. This is 
not part of INPUT; it takes an expression from BASIC, such 
as PEEK(123)+99, evaluates it, and, if the result is positive 
and less than 32768, it ig converted into a fixed point 
number heid in the two bytes ($61) within FPAcc. #1. 


Find array element or create new array in RAM, This is 
rather similar (to the routine which searches for simple 
variobles. However, the details of the array are held on 
the stuck, so the more dimensions an array has, the larger 
is the space used on the stack, And this routine is much 
longer and more complex, A leop checks for the existence 

of the subscripted variabie; it has two exits, one txken when 
the varlable is not found, and thy other taken when it is. 
Array variable not found; set it up. (DIM=10), 

Array varinble found. 

‘BAD SUHSCRIPT ERROR then READY. 

TILLEGAL QUANTITY ERKOR then READY. 

OUT OF MEMORY ERROH uand by next routine: 


Compute stse of array aubseript. Thid loops 8 times, and 
relurne with X and Y holding the slau required, X the tow 
and Y¥ the high bytes, . 


THEDIM'D ARRAY ERROR If the Citi fing (406 or $5D in 
WASIC 1) Is non-zero, 


Perform FRE. if atring mode is on, temporary atrings are 
theared and 'garbaye collect! performed. After this, Ui: 
pulnter to the lowest stelng ininus lhe end-of arrays politer 
Ix stored in A and ¥, noc put inta FPAcc, #1;- 


Le I TRE An ie nt A RE I RA Be” 
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30205 $O27A $Cace 


$CACB 
$Cacr 


$D27C 
$D2ac 


$D287 
$0285 


$C4D4 
$c4D7 


$Cc4aDc 


$D285 
$b2938 


$D28D 


$D290 


$0295 


$D2C3 $D2BR SC5SOA 


$02D6 $02CE $s$CsiD 


$D389 $D33F $CSBE 
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Convert 2-byte integer inte floating-point, On entry, 

Y holds the low byte and A the high byte of an integer 

In the range 065535. This routine converts it into floating~- 
point form, leaving il in FPAcc. #1 (i.e. §5E holds the 
exponent, $5F-$62 hold the mantissa, and $63 is the sign.) 


Perform POS. Calis the previousroutine, ignoring whatever 
dummy variable appeared in POS(x). [t loads ¥ with the 
position of the cursor on its line (from $C6 or $05 with 
BASIC 1) and the high byte A with #0, then enlls the last 
routine, overwriting the contents of FPAcc. *l with the 
yatue of POS, Put contents of Y into FPAcc. Hi, 


Check for program mode. If the high byte of the current 
Mnenumber is #FF, this is a code used to signal that a 
comand was entered in direct mode (i.e. from the keyboard 
without a linenumber). 

*ILLEGAL DIRECT ERROR then READY. 

°TYPE MISMATCH ERROR then READY. 


Perform DEF (function definition). Some of the syntax 
checking is carried out by the next routine. This one tests 
for direct mode and the presence of a '(", then searches 

for and/or sets up its dependent variable, cheeks for ‘}=', 
and pushes § bytes on the stack, The first byte is the first 
character of the function definition, perhaps a variable's 
initial character or a token for LOG or SQK. Then the 
dependent variable's address and the current pointer into 
BASIC are stored; when 4 FN is addressed. the expression 

to be evaluated is calculated by temorarily restoring CHRGET 
to Its present valuc, pointing to the start of the expression. 
Finally, the next statement is scanned for, and the bytes 
are all popped and loaded into the function definition in RAM. 


Check some of DEF FN's syntax. This (i) Checks for a FN 

token (¥A5), Gi} Sets the function flag, ORing the Initial 

of the function's name wilh #80, (ii) Searches for this func- 

tion, setting it up if it doesn't yet exist, (iv) Checking that 
the type is numeric. (String functions aren't allowed). 


Evaluate FN, This routine (i) Checks FN with the last 
aubroutine, (ii) Evaluates the expression in parentheses, 
and checks that it's numeric, leaving the answer in FPAcc#!, 
without changing the value of the dependent variable, iii} 
Recovers the five values stored by DEF &S, (iv) Stores the 
current verinbles on the stack,(v) Puts the five Mosting- 
point bytes directly into FN’s area in memory, (vi) performs 
the evaluation, lenving the result in FPAcc. #1, and (vii) 
Pops and repluces the FN DEF duta in RAM. 


Perform STR$. This apparenly short routine in fact calls 
a rather longer routine, which Is an important one in string 
handling. STR$ first checks that the argument evaluates 
to a number; It converts the contents of FP Acc. f1 Into 4 
string starting at SHINO (80200 In BASIC t}, in the usual 
Microsoft form, e.g. with numbers snatler than LO) expressed 
in aclentific nototion, like GE 03. It throws away a return 
addruns (popping % byter from the slock) und wety painters 
to the buffer holding lae siriag; now, it's ready lo canvert 
the polnters inte a standard cera: page potater (net A und 
Y any more} and to measure Lhe teagth porameter, whieh is 
daturmined hy the Firat null byte encountered . 


Pa ater paAM, el NRE S 
ae ee ee er 


de ecient ttt rl ac EAI APA ee PN TT OE I EE PT ITE I ATES: 4 


$036B 


SDIAA 


$D2B0 
$D3D2 


$DaF4 


$Daa4 


447 
SIMA] 


$0359 SD35F 


$0361 


SD3A4 


$D3AA 
$DICE 


SDIFO 


$D400 


$497 
SDAAL 
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$CSF3 


$C5F9 
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$C65B 
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Allocate pointers and Jength to new string. Because fengths 
of strings are not dimensioned, each new string has to have 
its pointers and length recalculated. Thus, X$="ONE": 
X5="TWO" requires two calculations solety for this purpose. 
This routine requires that A on entry holds the length of the 
string; on exit, $5E holds the length and ($5F) points to the 
RAM area allocated for the string. The routine also transfers 
a temporary address, CHR$, LEFT$, STR$ and so on all use 
part of this routine. BASIC 1 uses $B0 and ($B1}. 


Set up string in memory, This routine is used by INPUT, 
READ, STRS, and other functions to generate space for a 
string in the high end of RAM, put the string there, and 
set the pointers for (say) X$ to point to it. Two Mags, 
$03 and $04 (or $5A and $5B in BASIC 1) are used for test 
locations here; they contain either quotes or, with a later 
entry point, : and , respectively. The quotes of course are 
redundant, except for the first, but they make the same 
routine usable for different purposes. Gn entry to this 
routine, A holds the low byte, Y the high byte, of the 
pointer to the start of string-1. The string may end with a 
zero terminator, or with ", or : depending on the type of 
string being processed. S5E holds the length, and (35F) the 
pointer, on exit; many other temporary pointers are used, 
{BASIC 1: $B0 and ($B1)). 

Sets string pointers- entry point from CHRS, ‘+, etc. 
?FORMULA TOO COMPLEX ERROR then READY. 

Allocate space for string. Gn entry, A holda the length of 
a string; this is the amount by which the current string 
pointer is decremented (using a 2's complement method). 
This is ($30) in BASIC>1 and ($82) in BASIC 1. The same 
result is put into the adjacent locations which hoid a ‘utility 
string pointer’, if the end-of-arrsys pointer overlaps the 
fowered string pointer the next subroutine is called: 


Garbage collects or prints ?0UT OF MEMORY and exits. 
After a garbage collection, the previous routine Is re-enter- 
ed. A flug in $69 ($60 in BASIC 1) ensures this process 
isn't endless by being get on exit form this subroutine with 
bit 7 high, then tested on re-entry. So garbage cullection is 
done once only. * 


Garbage collection. This Is a long routine which tidies the 
strings in the high end of RAM, and their pointers. To 
watch this in action, sue Chapter 2 for programs, BASICs 
prior to 4 are notorious for the slowness of their garbage 
collection, if a large number of strings have been defined In 
the hlgh area of RAM (i.e. not null strings or strings whose 
polniers point back within a program}. In practice, this means 
string arrays, (Numeric scrays don't need garbage collection). 
This formula: Time In seconda=.000084(n+11}7 gives an 
accursts approximation for the time teken by n strings to 

free memory. ASIC 4 has a ahorter and fer faster routhre, 
This operntes on the pointern ($444) wad ($50), Several 
subroutines subtract A from these in the course of memory 
freelng. In aurller BASICa lhe following coutinea have been 
identified : 


Cheek for most olgible string collection. 
Collect 4 string, 


th hug haw been reported in which BASIC 4 printe 20UT OF MEMORY inateed of garbage — 
coliscting when three atringa ere concatenated, 
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Perform string concatenation. This routine apparently 


works by adding the two strings’ lengthsallocating that 


amount of space in memory, then 


the apace side by side and finally setting up the name and 


putting each string into 


pointers for the entire new string. ($61) is assumed to 


point to the first string; the second is input and evaluated 


oy this routine. 
$D530 


$0552 


$D$32 
$0554 


SCTGA 


$c7ac 
routine which uses A to hold the 


STRING TOO LONG ERROR then READY. 
Store string in high end of RAM. Comparatively simple 


string length, and ($1F) 


as a temporary ponter to the start of the string. [t also 


uses the utility pointer ($32) to 


transfer the data; oan exit 


this points to the end of the string. BASIC 1 equivalents 
are ($71) and ($84). Several entry points are used:- 


$D552 $0554 $C7aC 


RAM. (in BASIC 1, (SS8E)). 


$0560 $0562 $C79A 
following the variable's name. 


$D564 
$0578 


$DS66 
$0570 


SC79E 


$C7B5 Discard temporary string, This 


($6C) points to the byte just after the variable's name in 
A holds iength, X and ¥ point to the byte immediately 


A holds length and ($1F) the temporary pointer. 


routine befins by loading 


($i1F) with a pointer to the strings parameters; on exit, 


the same pointer ($1F) points to the actual string, and the 
bottom-of-string pointers are moved up by the length of the 
string, ao that it will be overwritten by the next string to 


be defined. (This is only done if 


the string was the very 


last to be defined}, BASIC 1 uses ($71). 


$D5B3 $D5B5 $C811 


Ciean the descriptor stack. A holds the low byte, Y the 


high byte of a string vector; if these match the temporary 


store in ($14), ¥ is Icaded with 
and $13 and $14 are loaded with 


#0 (and the Zz flag set) 
A and A-3. The purpose 


of this is mysterious to me. This is used by the previous 


routine. 


$psCh $05C6 $C822 
that a l-byte space is available, 


and sets up the string details, 


Perform LEFTS. 
Perform RIGHTS. 
Perform MiD$. 


$Ca36 
$C862 
$c860 


$0500 
$D604 
$D60F 


$05DA 
$0606 
$0641 


Perform CHR$. All strings of the type CHR$(n) have 
length 1; this routine simply Inputs the parameter, ensures 


puta the character in it 


Each of these routines uses the second part of LEFTS (from 


DSE6/D5E6/C 943) to allocate spnce for the atring and eet it 


up in memory with its pointers, The length of the new 
substring and its starting point within the string, which 


were eariler pushed on the stack 
used to construct the substring. 


notobly MIDS which has two valid syntaxen, deal mostly with 


, are later popped and 
The rest of the routines. 


syntax checking anid wlth processing parameters. For 
example, RIGHTS pulls the puramaters (sue next routine) 
including nin RIGITS( S$.) whieh Is hiuld InAund X. 
The lengin of KS is reduced by nm befure entering LERT $s 


routine; so RIGHTS picks o subst 
Note that some validation Usices pt 


ring starting: wilhin XS. 
ace to guarnates that the 


string doesn't reavh beyond the end of its parant atring. 


Thia '4 done by comparing the st 
Piranetars and seluetag whichay 
tha carry flag, 


LT APT TLL IS SE gn ee rane ine re irre paren acme ae: 
ata Peal oa Siar, i 


ring'a tenth with with te 
or ly leads with the help of 


A ee mig! ie SP I NEURO TIO RS TS * 


| 
| 
| 
| 
| 


dag oe eo 


* 
Thee, 
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$D654 


SDG5A 


$D663 


$D130 
$0673 


$0685 


$D6C4 


$DECA 


a RR REN oe Oe TY FE TENE A TL ALRITE NOR, (AINA IY = ARTIS RAP 8 TA RY RRR | Areearemee = 


$D656 


$b65C 


$D665 


$D672 
$D675 


$0687 


$DéCH 


spece 


sC8Bz 


SCB8BS 


$Caci 


$C8CE 
$c8o1 


$CBE3 


$C921 


$C927 


15: CBM BASIC ROMs 


-4it- 


Pull String function parumeters from stack. The diagram 
Dlustrates the working of this subroutine, which is called 
by each of the string functions. [t first checks for the 
existence of a right parenthesis, '}', then pops (3iF), the 
pointer to the string, and its length, from the stack. On 
exit, both A and X hold the length of the string; Y is set 
to zero. BASIC 1 has a slightly different routine; and its 
pointer address is different. It uses ($9F). 


The stack before: and after: 


SP; 


SP; 
Perform LEN. Calls the next subroutine, from which it 
returns will the string's length in Y. Then it jumps into 
POS, where Y only is placed in FPAcc. #1 in floating-point. 
Load length/ move into numeric mode from a string. 
VAL, ASC, and LEN each call this . [t checks for a string 
and points to it {with ‘discard a string'}, loading the acc~- 
umulator in the process with its length. [t sets the mode 
flag to numeric (307, or $5E in BASIC L, is #0). Finally, 
TAY puts the length into the Y register in addition to A. 


Perform ASC. This calls the last routine - and rejects a 
string of length zero - then just loads A from the temporary 
pointer which it set up, t.e. (S1F), This is put into floating 
polnt form by entry into POS. Note that only the initial 

of the string is dealt with. 

Jump to print error message (‘illegal quantity’). 


Evaluate and input a l-byte parameter (0-255;. GETCHR 
must point to the expression, which Is evaluated and 
checked for range and type and also rounded down. The 
result is left in $62 and X; and A holds the character at 
the end of the numeric expression. With BASIC Ll, the 
parameter is returned in $B4. 

Functions which interact with machine code need some such 
routine as this ane; for example, POKE, 


Perform VAL. YAL apecates by treating its string ax a 
buffer, and seanning it with the routine which converts 4 
string into Moating-polnt in FPAcc. #1. The exception is a 
zero-length string, which returna VAL =0. Several para- 
meters are stored and later retrieved, when the conversion 
process ja over, 


Evaluate and input parameters for POKE und WAIT. Typically 
POKE $2345,6 and WAIT 23156,7 are the slatements which 
this rouline Inputs and cheeks; Sirstly, a numerig expredsiusn 
ix wevalugted, then converted (sce next rovline} into a I byte 
Witeger. The comms ty then cheeked for and ie next para~ 
mater celeulatud and put into X fare lust-hut-ors reitine). 
WAIT 323,456 is cheeked by re enlering the routine. This 
has to be tefl until the frst l-byte parameter ban besa deail 
with, of course, The lorger paraaecter is deposited ia Osi) 
and in ($11), where i (4 lesa tronsient. Thar olher jocutions, 
In FPAcc, #1. In lable da be averwritlen, BASIC J uses ($09), 
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Convert Floating-point accumulator #1 into 2-byte integer. 
This checks that the number is positive and within the range 
6-63535; then calls the conversion routine in DB6D/DBAT/ 
CDD1; and finally stores the result in ($11), or, with 
BASIC 1, ($08). This is used by AND, OR, WAIT and some 
other BASIC commands where & 16 bit number 1s wanted. 


Perform PEEK, On entry, flonting-point accumulator 41 
(i.e. $5E-$63) hotds the address to be peeked in floating- 
point form. On exit, Y hulds the peeckcd vatue, and it's 
reconverted to ftoating-puint format. This ts done partly by 
the last routine, which puts the address into a convenient 
form to access memory. Note thet BASIC 1 tests the PEEK 
address to reject some values and return zero. And its 
floating-point accumulator occupies different memory slots, 
from $50-$K5. 


Perform POKE, Gets two parameters, puts the second into 
A, and stores A into RAM where the 2-byte parameter points. 


Perform WAIT. Gets two parameters. and an optional third, 
which otherwise is made zero, The address parameter is put 
into ($11), the first byte parameter into $46, and the other, 
optional, parameter into $47. Now WAIT fs performed, 4 
loop which continues until the address, exclusive-ORed 
with the third und ANDed with the second bytes, is not 
vero. BASIC 2 (net 1 or 4) has Microsuft's joke here. See 
WAIT in Chapter 5. Or try. say. POKE 70,n:SYS 55121. 


Add .5 to contents of FPAcc. #2. A (low byte) and ¥ (high 
byte) point te .5 in floating-point form in ROM, then the 
addition routine is entered. Used when rounding. 


Perform subtraction. Repluces FPAcc. #l by FPAcc. #2 minus 
FPAce. #1. On entry at this entry point, A must hold the 
low byte and Y the highbyte of a pointer to & S-byte 
floating-point constant, which will be loaded into FPAcc. #2. 
On entry here, however, both floating-point accumulators 
are assumed to be loaded, and their contents will be sub- 
tracted as { ‘ve indicated. 


Perform addition. Replaces FPAcc. #1 by FPAcc. #1 plus 
FPAcc. #2. On entry here, A must hold the low byte and 

Y the high byte of 5 pointer to a 5-byte floating-point 
value In ROM or RAM. This wilt be loaded into FPAcc. #2. 
then added to FRAcc. #t. The result Is in floating-point 
form. Lf the value to be added is zero, the routine jumps to 
simply copy FPAcc. #2 into FPAcc. #1 without any further 
culeulations. ‘This entry point mokes thie test-it assumea 
that A holds the exponent of flanting-polnt accumulator #2'8 
contents, i.e. the contents of location $66 or $8 in BASIC 
1. 1f this in ao, the test will speed up additluns of zero. 
Finally, this entry point adda the two numbera without any 
speci test. 

Add two numbers which have equal exponents. (in other 
canes ong of the numbers ly modified until both have equal 
exponents : 

Heptnce FPAce. #1 by ita Ma complement, tl.e. all the bits 
of the necumulator are Dipped, then 1 In added). 
POVERELOW ERHOR and READY. 

Multiply a byte subroutine. 
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$CHCS 


SCBEF 
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$0018 


sCC2F 
$cecs4 


$ccib 


$CCas 


SCCIA 


#cced 


Table of constants: 1,then constants for LOG (byte of 3 
which is a counter for the series calculation, then 
4342559, .5765845, .9618007, 2.88539), and 4 SQR(2}, 
SQR (2), -.5, and toge2. 


Perform LOG ta base e, See Chapter 5 on LOG for an 
explanation of this function and its operation. 

Perform multiplication. Muttiplies the contents of FPAcc. ii 
by the contents of FPAcc. 42, leaving the result in FPAcc #1. 
This first entry point assumes that pointers are set to the 
second value in memory, held in 5-byte floating-point 
format. These pointers are: A to the low byte, and Y to the 
high byte, of the start of the value, As an iijlustration, note 
that D6FS/D930/CBSA point to loge? and then drop through 
into this routine,thus multiplying floating-point accumulator 
#1 by loge2. (This of course is part of the previous func- 
tion ). Note that the routine which loads the second floating 
point accumulator also loads A with the exponent of the first 
floating-point number; in this way, if the first number is 
zero, nothing more need be done. 

Multipties the two flouting-point accumulators without loading 
either of them afresh. The result is left in FPAcc.l. 
Multiply a byte and store the result in the product area. 
{This is a temporary accumulator in locations $23-$27. 

In BASIC I, $75-$79), 

Load Floating-point accumulator #2 from memory. This routine 
takes the value held os a S-byte floating-point number and 
puts it into floating-point accumulator #2. [n the process it 
unpacks the sign byte and stores this separately. These 
jocations are used: 

$66 (exponent), $67-6A (mantissa), and $6B (sign). 

Qn exit from this routine, A holds the sign of the number in 
floating-point accumulator #1? fnot #2). Pointers: Alow, Yhigh. 


Multiplication sudroutine to check both accumulators. 

This checks various conditions; if FPAcc. #2 is zero, then 
FPAcc. #1 is made zero; if the exponents together are too 
large or too small, °OVERFLOW ERROR or zercisation of the 
reault respectively take place, 


Multiply Floating peint accumulator #1 by 10. This short 
routine doesn't use a volue of 10 in ROM; instead it multi- 
plies accumulator #1 by 4, adds this reault to itself, and 
doubles the result. At each stage it testa for overflow. 


Constant: 10 in 5 bytea of floating~point. (84, 20,0,0,9). 


Divide contents of floating-point accumulator #1 by 10. 
This moves accumulntor #1 into accumulator #2, then sets 
pointers to 10 and performs dlviaion. 


Perform division Into fioating-point accumulator #2. On entry, 
A.Y, and X hold the low and high pointers toa S-byte value 
and the slgn comparison byte, in that order. Then FPAcc. él 
in londed-feaving FPAcc. #2 unchanged- and the result of 
FPAcc. #2 / FPAce. #l calculated and Jef¢ in FPAcc. #1. 


Perform division: FPAcc.#2 / FPAcc. fl Into FPAcc. #1. 

This ontry point loads accumulstor #2 before the divialon, 

uaing tha routine at YSE/DY98/CHC2, x9 the polaters A and 

¥ aunt bo arranged beforehand. The following entry polnta: 

pestis the pronent accumulators wlthout changing elther of 
om. 

TOIVISION BY ZERO ERROR then READY. 


2h ote REI EL RA Rea, I ei ned ot A AC ates tae er ces tae 
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SDAAE $CCD8 Load Floating-point accumulator from memory, This routine 


$DAD3 


sBADC 


SDAEO 
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$DB18 


$0827 


$0837 


$0845 


$CCFD 


$cD06 


SCDOA 


$CO32 


$CDa2 


$CD51 


$CD61 


$CD6F 


takes a value held as a 5-byte floating-point number and 
puts it into floating-point accumulator #1. In the process it 
unpacks the sign byte and stores this separately. The bytes 
are taken from the memory locations pointed at by A (low) 
and ¥ (high). Sce, for an example, the routine starting at 
DIDO/VADA/CC34 which loads 10 into floating-point accumul- 
ator #1 then divides this into FPAce. #2, The locations used 
are $5SE (exponent), $5F-$62 (mantissa), and $63 (sign), 
Note that zero sign bit means plus, #FF means minus. 


tore Floating-point accumulator #1 into memory. This packs 
the sign byte and rounds the accumulator, so that it Hills the 
standard § bytes of a numeric variable. I[t is stored into 5 
bytes starting with the sddress pointed to by X Clow byte) 
and Y (high byte). There are four entry paints: two of 
these point to special zero-page locations in which TAN and 
series expansions are worked out, (l.e. $599-$5D and $54-$54). 
The third entry point stores the value in the location which 
($46) points to (or ($98) in BASIC 1), This is used by LET 
and by the FOR-NEXT loop to store an evaluated quantity 
in a variable's storage after a BASIC program. 
Finally, this entry point is the one to select when the X and 
Y values have to be set explicitly and don't correspond to 
those cast in the silicon of ROM. 


Copy accumulator #2 into accumulator #1. This moves the siga 
and five data bytes fram one accurutator to the other: both 
now hold the same value. The rounding byte is nade zero. 


Round and copy accumulator #i into accumulator #2. Calis the 
following routine, moves @ bytes of the accumulator (more 
elegantly than the last routine!), and zeroises the rounding 
byte. Each of these short pieces of code therefore loses 
little information. : 


Round accumulator #1. The rounding routine doubies the 
rounding byte and exits without action if the result has the 
carry bit clear, showing that it was less than 128. {t also 
exits with zero (this ig always gignalled by the expanent’s 
value bring zero). However, if the curry bit ls set, 6 gingle 
bit is added to the Mosting-point value; this process can be 
traced in ROM, Each byte is incremented until the result of 
the increment ig not zero (which of course is usual). Lf the 
addition propagates through the eccumuletor, a routine is 
called which adds ane to the exponent and also rotates all 
the bytes right. In this case, the rounding dit is lost . 


Find sign of accumulator #1. On exit, these valves apply: 
A-:0 means value is 0. 

A=l meank value is ponitive. 

A:#FF means value js negative. 


Perform SGN. Because BASIC function arguments are put in 
floaling-point accumulator #1 after evaluation, SGN euilln Une 
previous subroutine to compute ity sien. This fs placed in 
fonting-pelnt accumulater #L aa abown here; 


_ SSE] $5F $40) $01 SUZ 363 
e$hAlsign’ oO |] uv oj 


and o subroutine in the ‘adstithea' suulines ia called to 
conyert G1, of #EF into their fluathag point form, nernallsed 
and with the sign byte act. Sea the noxt subroutines. 


7 


Pt me RR A A a ees I Oe ewe 


Programming the 
BASIC? 


BASI CI 


SDBOE $DB48 


$DBL6 


$DB2A 
sDB2D 


$0860 


$DB9E 


S$DBBB 


$Dacs 


SDCIC 
$DC50 


$bDC45 


$0094 


SiKOF 


$DB50 


$0864 
$DB67 


$DBA? 


$O0B8DB8 


SDBFS 


5SOBFF 


$DCT6 
$DCAA 


$DCBF 


$0CCE 


$DCDI 


PET /CB8M 


BASI Ca 
$CoT? 


SCD7A 


$CDSE 
$CcD9L 


$cpot 


$CEOZ 


$CE1P 


$CE29 


$CEAQ 
SCEI4 


$CER9 


3CF78 


$CFCI 


pee me AA RO Roe Sa Re 


15: CBM BASIC ROMs 


~415~ 


Store contents of accumutator onty in accumulator #1. 
Example: LDA #A0 / ISR CD72 puts the value 160 (decimal) 
in floating-point form in FPAcc.#l. 

Evaluates a doutle-byte integer and converts the result into 
floating-point form (0-65535). On entry here, X must hold 
#590, SSF the high byte, and $60 the low byte, iike this: 


$9e| $57 
#$90/sign 


Note that the carry bit indicates the sign in all these 
routines. If it is set. the number is treated as positive and 
vice versa. 


NOTE: The values #88, #90 (196, 144 decimal} are exponents 
indicating the size to which the number is to be normalized. 
Numerals of three or four bytes can be evaluated by an 
extension of this calculation routine. See INT. 


Perform ABS. See Chapter 5. 


Compare Floating-point accumulator #1 with S-byte floating- 
point number. A (low byte) and Y Chigh byte} point to the 
§-byte value in memory. On exit, the accumulator (A, not . 
one of the floating-point variety) indicates the relative sizes: 
A=0 means the values are equal. 

Al means that accumulator #1 > memory. 

A:#FF means that accumulator #1 © memory. 





Convert Floating-point #1 into integer, within FPAcc. Fi. 
This routine is called by D6DA/D6D2/C92D which, however, 
also treats the fixed-point number as an eddress, which it 
stores in ($11), or, with BASIC 1, in ($08). 


$60 136.1} $62 |$63 
ai+| #1 | to | 


Perform INT. Acts on floating-point accumulator #1, rounding . 
it down to the nearest integer, but leaving the result in 
floating-point form. 

Used when zeroising all of accumulator #1 when the exponent 
has been found to be zero. 


Convert an ASCII string into a numeral in FPAcc. iN. VAL 
and other rceutines use thie to evaluate 4 Rumeral which is 
in string form. GETCHR should point to this string before 
entering this routine; then JSR 0070/ JSH CE29 (or what- 
ever other values apply for BASICs 1 and 2) scans the 
string and puts the result in floating-point accumulator #1, 
E. + ~ and teading and other spaces are apecially checked; 
the routine to multiply by 19 adds together consecutive digits 
as they are encountered, 

Add new ASCIP numeral to the mantlasa. 

Add contenta of A only to floating-point accumulator #1. 
Examplu: LDA #S$0F/JSR CEW4 adds 15 to the accuaulator. 


String conveculon constante., There are three of these: 
99 999 999.9, 999 999 999.75 and | 009 O00 000, 


Print IN followed by linenumbar, JN ia a messige from the 
atondore tuble, The Mnnnamber la printed by tonding A ane] 
X with the high and low bytes respretively which are atored 
fn (3383, or (SBE) in BASIC 1. This ia the current line~ 
number, which js stored by RUN a4 WASIC ik cxeeuted. 

Thin prints 256¢A * X on the following line, 


ine cong tec per ep a cn YR SE i ET A PN TE I pth 
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Convert contents of Ficating-point accumulator #1 into ASCII 
string starting at $0706. On exit, A and Y hold #0 and #1, 
pointing to $0100, so that the print routine CA27/CAIC /BBID 
can print the cesullt as a string. Note that the buffer is at 
the lowest end of the stack, inaccessible to BASIC, Chapter 
2 has a table showing how this fomatting process works in 
practice. Note the zero terminating byte, and the special- 
case processing for zero. PRINT USING, in Chapter 5, 
demonstrates how this routine may be adapted to get other 
gutput formats. 

Note that FPAcc.#1 is changed when this routine has been 
run. The tables of constants following this routine are used 
in the comparison/ conversion process. The later ones deal 
with TIS. And the three values tabled before this routine 
are used to decide when scientific format should be used. 
Convert T1$ from three bytes into the corresponding string. 


String conversion and T1%$ constants: .5 for SQR and round- 
ing, then 15 4-byte constants, -160 000 000, 10 900 000, 

=1 000 060, 100 006, -10 000, 1 O0U, -100, 10, -i and 

-2 160 001, 216 00 (=1 hour), -36 900, 3600 (=1 minute), 
-606, 60 (=1 second), 


Perform SQR. This puts FPAcc.#l intu FPAcc. #2, loads 
FPAcc.#1 with .3 and performs the next routine: 


Perform power calculation (t). Calculates FPAcc,#2 to the 
power FPAcc. #1. Mote that FPAcc. #1 may be loaded from 
memory by setting A and Y pointers and entering one 
instruction earlier. FPAce.d#2 must be loaded before running 
this routine. Both numbers are tested for equality with zero 
and if zero is found, set the result in FPAcc.#1 to Qorl 
according as FPAcc.#1 or FPAcc.#2 is zero, The function is 
evaluated by saving FPAcc.#1 in the zero page, then 
multiplying the togarithm of FPAcc. #2 by FPAcc. #1, and 
finding the exponent of the result. 


Negate contents of floating-point accumulator #1. Changes the 
sign byte with EOR #FF, so 0 becomes #PF and vice versa. 
FPAcc.#1 is unchanged if it equals zero. 


Table of constants: I/log,e and % constants for EXP‘s series 
evaluation: byte of 7 then 2.149876 E-5, 1.435241 E-4, 
1.342263 E-3, 9.614017 E-3, 9,550513 £-2, 2.402261 E-1, 
6.931471 E-t, t. The series in fact calculates dn. 


Perform EXP, The vulue esFPAcc.#1 la computed and Jeft in 
FPAce.#l. For notes on the method and on the weries used, 
aee Chapter 16. 


Function evaluation routine: thls calis the next routine. It 
evalustes more complex expressions of the type qtintq*x), 
where fn(x) is evaluated by the series expannion formula 
embodied In the next plece of code: - 


mA, MR a i seat, AA na! AO Ne | 


Main series evaluation routing. Ail the mathemmtion) fimations 
(LOG ,SIN, COS, efe,) are evelunted by tranaforming Une 
argument into a aultable range e.g. O1), calculating the 
reauit and Finally, where necessary, modifying the result - 
perheps by chengiag the slyn or altecinge the exponent, 
This aubrouting: must be entered wilh the polnters (6H), oF 
($C0) In BASIC 1, looking ata single byle, whieh will be rice 
an the number of values In the table. Then by a repet (tive 
process the tnbled values are addled and multiplied to PPAcc# 
no the table byte MOS3/7 710 Chor exeapled Heda the value of 
10 * 3x 6 Sx? Sen Chapter 16 for mure on Tala subject. 


were 
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RND - multiplicative constant. (=11 679 546.4) 
RND - additive constant. (23.927 677 78 E-8) 


Perform RND, The firat three instructions of this function 
compute the sign of accumulator #1 (and hence of the arg- 
ument of RND) and branch to three sections of the routine 
according to this sign - counting negative, zero and positive 
as different ‘signs’, All three branches meet and exit from 
the routine together. Briefly. what happens is this: 

Zero argument. The four bytes $5F~$62 in FPAcc, #1 are each 
loaded Fron the VIA timers; 2 of these change with every 
clock cycle, so there's some justification for calling this 
'yandom'. (BASIC 1 uses the wrong ROM addresses here, 
probably because the final positioning of the chips wasn't 
settled when RND was written). Then jumps to common exit. 


me eit: 
: M 4 : Sign Round 


Positive argument. Multiplies the stored random number by 
the first constant at the top of the page, then adds the second. 
Then continues with : 

Negative argument. Interchanges bytes as marked. 

fommon exit routine. This puts: #0 into $63 (i.e. positive), 
Exponent into rounding byte, and 4$80 into Exponent. The 
latter forces the result into the range 0-1, the former perhaps 
is intended to ensure that the exact value 0 does not occur. 
Finally, FPAcc.#1 is stored into the random number work 
area, ready for the next positive argument in RND. 


Perform COS. Puts pi/2 into FPAcc.#2 and adds; then: 
Perform SIN. Evaluates SIN of FPAcc. #1 and leaves the 
result in FPAcc. #1. The argument is in radians, See Chap- 
ters 5 and 16 for more information. 

Perform TAN. Evaluates TAN of FPAcc. it, by dividing 
the sine of that value by its cosine. As the argument 
approaches 90° and other values {pi/2) the calculation wil! 
inevitably lose precision. 





Table of constants: pi/2, 2*pi and .25. Then there's a byte 
which acta as a counter; it is 5, and the constants following 
(6 of them!) are -14.33139, 42.007797, -76.70417, 81.605223, 
-41,3417021, and 2*pi again. These are used by SIN. 
BASIC 2 has algo [TEOSORCIM in eneeded form. 


Perform ATN, The arctangent is left in FPAcc. #1 after 
evaluation; it's in radiins. It is calouluted with the aid of a 
acrics with 12 turms; this is the longest serles used, but it 
also happens to be based on the simplest, and Is optinised 
for the range 0-1. (The basic series in x - xt/3 + x5/5-...} 


Counter and table of 12 constunta for ATM evaluation. 
These ure; "6,84793912 E-4, 4.85194216 E-3, -, 0161117018, 
034209678, - 0542791928, .0724571965, - 0898023954, 
240939433, ~.142859K0K, , 19999972, 39933016, and 1, 


CHRGET routine and RND seed for relocation Into RAM. 
BASIC on reset moves hol these tubies into RAM, starlings 
at $70 Cor $2 In BASIC 1) where they are positioned con- 
Kecullvely. In fuct only 4 bytes of RAND are tronaferred, #0 
jin yuiue, Uheoreliaily .A1{635157, could prexummbiy vary 
within the range .WUIGUSLS7T - AliG51 98, 

Entry te ROM CHRGET where the foced address 1h wnbiport- 
ont, at SEC/SBE #0 Gta. Can be need ta nave zero page 
dylon. If ihe program fas no apices an earlier entry point 
niny ba went. 


Fe ance FRA ly ENR ERE AT PE CAE IC I a oer aE ee NE PI mm 
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$EGD2 


SEQES 
$E10C 


$E131 
$E167 


SELSA 
SEL74 


$E116 


$EL2F 
SEL5S2 


SE174 
$EL96 


SE19D 
SE187 
and 


$FOit 


$FDI7 


$D3B6 


$DI3C7 
SD3EA 


$paiz 
SIH 2A 


sDH91 
$0448 
SDEA4 


SDSF9 


-$13- 15: CBM BASIC ROMs 


Test RAM and Initialise BASIC. This routine 1s the final call 
made by the system on reset, including switch on, when the 
reset vector at (FFFC) is culled, This first sets input/output 
values before jumping to this routine. Note that there is an 
alternative path on reset, used by Jim Butterizld’s technique 
for resetting BASIC 2 and 4 machines, which enters the 
monitor without disturbing BASIC. In BASIC 1 this leads to 
a diagnostic program, not a monitor, 

A SYS call to the appropriate address above, or an indirect 
jump to (FFFC) with any ROM, erases RAM memory above 
$0400 and resets all the BASIC pointers, and so is a reliable 
way to return memory to the cold-start situation which obtains 
when the machine is turned an, {Note that an indirect jump 
ia represented by opcode $6C=108 decimal. So POKE 10% and 
252 and 255 into consecutive locations and S¥5 the first of 
these to reset any ROM), See Chapter 13 for an account of 
the events of Reset. Some major locations sre: 

Move CHRGET subroutine and RND seed to zero page, 

Start of BASIC becomes $400; RAM test and exit. Note that 
A holds #0 on entry. From $0400, #355 fi.e. $OL010L01) is 
written to RAM and read tack; then #SAA (%$10101010) is 
written and read.*This is a standard type of chip test, When 
the read-back is not equat, or $8000 has heen reached, the 
next routine is dropped into: 

Set BASIC string and variable painters to their start vajues. 
Print *** COMMODORE BASIC *** (BASICH), 

$## COMMODORE BASIC ### (BASIC2), or 

*#k’ COMMODORE BASIC 4.0 *** (BASIC 4). 

Catculate and print oytes free. 

Tables holding the messages for bytes free and for Commod- 
ore BASIC. The second tabie tor BASIC 4 seems to be an 
afterthought. It includes ‘4.0°. 

Prints 44030 bytes free. (Joke?). 


MACHINE-LANGUAGE MONITOR (MLM). 


$Da72 


$D478 


$FO56 SDABA 


‘Call’ entry to monitor. This printa C* followed by details 


Hie thle: Pc IRQ SR AC XR YR SP 

-} BY80 £455 32 38 2C 34 PA 
PC points to HASIC; [RQ and SP are taken from the stack and 
are reliable. The ‘registers’ are garbage from the input buffer. 


‘Break’ entry to moniter, This prints B* and pully the stack 
to determine the contents of the program counter and reg- 
jatera: it agsuines an entry by SYS 1024 or SYS 4 froen BASIC 
(or any location hoding a zero byte), or by a machine-cade 
routine entering 4 BRK instruction. SYS to this address will 
remove data from the stack, Note that BASIC 4 differs from 
BASIC 2 {a restoring normal devices on BRK, so the monitor 
always prinia to {he sereen, In order to dump monitor inform 
ation, use the cul) entry: OPEN 12k,4; CMD 12H, "MONITOR: 
SYS S446 which directa output to the priiter. PRINT RIZE: 
CLOSE 128 unllstens the printer, (These figures are for 
printer witb autanutic te feud oft). 

Start point: walts for command after . and execules (It. 

For example, . Mf td00 TORO id processed from tere: Mts 
suarched inoa Libby, atmlagourn te the BASIE keyword tabbe, 
and itiaddresa 2 pushed on the atack. RTS fiien jump. 


BASIC has a lese thorough tost, using #$02 and #424 (410010070 and ZnOdngLag) . 
Tho intention, to teat wii the bite, ima the sane, 


“PE ER, tepid eee ea ery Pt td 2 PR AI mw aS mm RN ARES ape ay =m arn Sm erie epee 
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BASIC2 BASIC4 


$FD70 


$FD93 


$FDA? 


SFDBF 
SFOCA 
SFDCD 
$FDDO 
$SFDBS 


SFDEO 


$PE23 


$FE58 


$FE97 


SFEB9 


$FECF 


SFFQ? 


en ee ae 


$0405 


SDaF? 


$D50B 


$B523 
$D52E 
$531 
$D534 
$D539 


$0544 


$D5a7 


$D5BC 


SD5FB 


$B610 


$0633 


RISE ET 
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Search taute of commands. Compares 8 single byte commands 
with that input. (: 7; RM GX LS). if not found, jumps to 
the address USRCMD, (S03FA}, which is set up to point ata 
routine to print ? crif, then jumps to START. This RAM 
address may be altered to include one'’a own monitor commands 
such as those used by Extramon. 


Cisplay memory. On entry, A holds the number of bytes to 
be displayed, and ($FB) holds the first address. 


Read a byte and stora in RAM. Reads a byte into A and 
stores it in (%#8), exiting with ? if the readbrck doesn't 
equal the byte. Increments the pointer (SFB). 


Sets (SFB) ready to $0202. On exit, A holds #5. 
Print two spaces. 

Print one space. 

Print one carriage return + line feed. 

Increment temporary pointer locations (SFB). 


Three tables for MLM. These are: 

di) ASCH values of commands : ; RM Gxtls, 

(ii) Address high then address low bytes corresponding to 
the address of each command less 1, 

(iii) Dext storage of (Rtn) PC TRQ SK AC XR YR SP. 


R (Display registers). Prints 29 characters of the text tabie, 
foliowed by the program counter and 1RQ as 'words' and 5 
other bytes, all from the input buffer. These record the 
situation a5 it was at SRK, i.e. SYS i024 ete. 


M (Display memory). Most of this routine is validation and 
housekeeping. Sets of B bytes are displayed using 'Disptay 
memory’ (above) with As#8. (SFC) holds the upper limit 
beyond which memory won't be displayed, except as part of 
the last &byte block of data. 

; (Modify registers}. This inputs the new program counter, 
storing it in 0200 & 0201; IRQ similarly is put in 0207 & 0208. 
Finally, 5 bytes are read and stored in $0202 ff, The layout 
within the input buffer is this: 









at $0205 | $0206 | $0207 |s020% 
aAcc's# | XR) YR SP F ERQ nt! LRQ lol 





Note that the registers are not modified by R; only the input 
buffer stores these values, which ore loaded by G, the ‘go 
run’ command, 


: {Modify memory). Reads the memory address into (SFR), 
then rends-ond-steres @ bytes into RAM. This routine is used 
by the lutter routine also; in its case (SEB) points to $0202 
and only 5 bytes are atored. Thia routine atups, prinling 4 
query, If on rendback the byte dovsn't have the write value. 
This hsppens on trying to write to ROM fer Instanee. 


G (Go, Go run). Thhs command has two formats. Go alone 

Telehes alt Une regivbers From $0200- $020 nnd Jodtls thet, su 
ft4 destination is deterinined by Che proyrent caubter Staves 
in $0200 and $0203, G ABCD overwrites the pragraci rosates 


dfere with SARCD, but lands the other registers put as 


does, The edtect ds that any routine cam be catled, sith eny 
values of ASX.Y, processor sinvk, ane IR. 


X (Exit to BASIC}. Sutx the stuck Poinker to its entry value 
ard Jumps ip HASIC warm tect (COARSER) where KHELADY 

Ja prided ancl a freee Commer awaited, The panypriaa saat 
Ita variables wm: all promerved bitaet ‘Che input vitter reyvorts 
ta ity WASEC bryput haffor rote. 


A ne AE TPO aD rank mb Time AmmeSL TS SAUCER OT a5 = SS CTE RA NS aie Ne HITE 
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BASICT BASIC? BASICS 


$FFII 


SE7TGA 


SE775 


$E7a4 


$E78D 


$E797 
SE7A7 


$E7B6 


$E7E0 


$E7EB 


$E7F7 SOTAS ERROPHR. Print 7. Then ga ty Input Une next line, 


$D675 t /S (Load and Save machine-code routines). These are 


$0717 


$0722 


$0731 


$D73A4 


$0744 
$0754 


$0763 


$0730 


$D798 


mixed together because of the similarity in syntax. The main 

locations used are these: 

$B4-index of command in table (i.e. L=$, $+7), 

$96-ST byte. 

$9D=LOAD/ VERIFY select flag - Load-0, Verify=1. 

$Di-length of string (i.e. device number * naine, or, in the 
ease of defaults to tape, name only). 

$D4-device number (8snomaal CBM disk, l=cassette #1, ete.), 

{$FB) and ($C9) store the low address and high address for 
Save. (Load needs only the low address). 

(SDA) points the sturt of the string or filename, 


The syntax is shown by these examples: 

-& "M/C SORT’, O1 : REM LOADS M/C SORT FROM TAPE #1 
.$ “1L:0LD.039A",08,033A,0381; REM SAVES 0234-0380 ON DISK 

iL : REM LOADS FIRST FILE ON TAPE #1 
.9 “O:RAM DUMP",0D,0000,0100:HEM SAVE TO DEVICE #13 


When the above pointers have been set. the routine at 
F49E/F322/F956 performs LOAD without requesting para: 
meters, and the routine F6BL/F6A4/F6E3 performs SAVE in 
the game way. “These routines can be called from BASIC and 
represent the only feasible way of loading and saving chunks 
of machine-code from BASIC. 


Subroutines used by MUM. The names are Commodore's, 
WROA. Guput hex digits. Prints contents of ($FB) as 4 hex 
digits. for example 4C03. 

WROB. Output single byte. Prints the contents of the 
accumulator as 2 hex digits, for example F3. 


WRTWO. Output two characters. X contains the first, ¥ the 
second, character; in the monitor, these are set, by the 
next routine, to be 44-57 or 65-70, i.e. ASCII 0-9 or A-F. 


ASC. Convert 0-15 into ASCIi character. This takes the 
contents of A and converts to ASCII - sce previous routine, 


T2T2. Exchange contents of (SFB) with (SFD). 


RDOA. input full hex address, This seta the flashing cursor 
und awaits input of a 16-bit value, e.g. ABD&. The result in 
placed in (SFB). Carry is cleared if there are spaces only. 


RDOB, snput one hex byte. The cursor flashes and a sing!e 
nex byte (e.g. AH) is input to the accumulator, which holds 
the same value(e.g. AB'}, Carry clear meanta nothing was 
Input, 

HEXIT. Convert ASCIi numeral to HEX. Accumulator values 
of #30- 439 and #41-4#44, which print ag 09 and A-F, are 
converted to 0-#F in the accumulator, 


RDOC. Input character/ await return. Flashes cursor and 
inputa a single character. If this ia carriage return, tha 
gubpastiney return ls stepped, and the routine icin lo chock 
the commend fetter or punctuation symbol presumably prescrt 
at the start of the line. 


*BASIC 1, though without « muchine-esde Bonitur - unless TIM d'bany @unbtec’} or @ 

Supermon-atyla sonitor is loaded in + nevarthatenw haw LOAD and SAVE an RATIC roneands 
shich aro Usable from KASIC or mechina-code, The lucationsa are different: There Ia at 
index; ST te $02°%*; $0200 ta LOAU/YERTPY: €260 la Longth; $F) ta devices; tow and high 
addresnos for SAVE wre (¢F7? and ($05); and (8¥¥) points to the atart wf the filonary. 


_— 
sn RE 2 TI A INE TT NETRA RN NLS ER: RBS SI were! 
: % ee OS ' 


Programming the PET /C8M -42T- 15: CBM BASIC ROMs 
BASIC 4 


DISK COMMANDS - BASIC 4 ONLY. 


SD7AF ‘Perform RECORD. This routine validates RECORD #ile number, record humber 
[.optionat byte number}. The byte parameter is tested to ensure it's within 
the range 1-254; and it defaults to 1 if not explivitty mentioned. The logical 
file number is tested to ensure it is not zero; and the recurd number can 
take any 2-byte value. It may be written as an expression, but if it is, it 
must be within brackets unless it starts with a number. Thus, these are 
valid: RECORDEZ*2,(Q},} and RECORD#2,245,5. Commodore has intraduced some 
new rutes for validation into its disk commands, which are not quite the same 
as in BASIC itself. RECORD jumps to SDA31 to send its message to disk. 


$0804 4 disk BASIC parameter checking routines. These print °SYNTAX ERROR if 
the bits sct in $033E don't match a bit pattern that is looked for, and Ete) 
indicate that a wrong parameter has been entered, or a correct one omitted. 
$D82E for example checks that A has bits 0 and 2, at least, on. 


$0438 Dummy disk control messages. This table holds commands corresponding to 
10 instructions. The tables are used to construct full messages in the disk 
command butter. A simple example: BACKUP has 44 D2 3D Dt. 44 is ASCII 
Y and 3U is ASCU =. D2 and Di are not ASCII] values, but a coce showing 
that destination and source drives are to be substituted. The resulting 
string has the some effect as D1=0 which duplicates disk 0 onto disk L. The 
word 'BACKUP"’ is not used by the disk unit. 


$b 939 DIRECTORY or CATALOG ($ Di) 
$083B DOPEN etc. (D1 -F1,E£1,E0) 

$0842 APPEND (D1 :Fl,A} 

$D847 HEADER (N Di: Fi} or (N Dt:F1,D0) 
$D84D COLLECT (V Di ) 

$D84F BACKUP (PD D2=D1) 

$D853 COPY (C D2; F2=DL: Fi) 

sD858 CONCAT (C D2: F2=D2: F2, Dl: Fi) 
$b 367 RENAME (R Di: F2=D1: FL) 

$D86F SCRATCH (S D1: Fi} 


Some of these commands have alternative forms; HEADER mny have length 
4 or 6 in its string, COLLECT lor 2, CONCAT 4 or 12, depending (for 
example) whether HEADER's 1D is given or not. The following table shows 
how the dummy values (which are detected by bit 7 being high) are under- 
stood ; DO = DOS disk [D (2 bytes) 


D1 = souree drive number 

D2 = destination drive number 

EO = resd or write 

Ei = paramcter length {relative files} or 8 (sequential files) 
Fi = source file name 

F2 = dextination File name 


$0873. Perform CATALOG or DIRECTORY. Both of these commands jump to this 
addresa; they ore identical. The syntax checking test that $032E hns bits 
1,2,3,5,6, and 7 all off; only a drive number and string are permitted. The 
valldation ix performed by the routine $DC6#; to anve Kpace [ shnll not 
mention thix with each instruction, #lthough every cisk command except 
RECORD uses it. DURECTORY worka Uke, and closely resembles, the DOS 
wolge peograd. it Wats’ the directory, not in RAM, but by Iaoking for ead- 
of ling zero bytes, throwlng away the Hnk addcess, printiog (he ‘inetuaber 
which is the flelength, and printing each charneter of the name. Thus the 
Mating takes plaice witheut disturbing WAM, Nevertholess, the directory 1s 
atlll stored, as in DOS 1, tu program form, 

SDHAS, SDHAS Throw away 4 Water 2) bytes than print ‘inenumber’ 

BDY0G End of fine ated pacitle end of-progeam subroutine, 

4911 Exlt io Svoce 9 

SDA  Oulput a character. 1., set devien/ output! set default devices, Ennbles 
the directary to bo autput to pirintess ote. 


Se eee gee RE A RN RE NOR or EO ate = EO IN mr acme n® MINER ots aS it SSE SAI RAIS Oe 
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BASIC 4 
$092F 


$0942 


$D977 


$099% 
$D595 


$09D2 


§DAQ07 


SOAS! 


$DAC5 


SDATE 


$DA 9B 


$DAAT 


$DAC?7 


Sead cacti oe 
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Find next available secondary address. Sets $D3 (=secondary address) to 
#62 + by searching all the open files until an unused secondary address is 
discovered. At each loop the trial value is incremented, This saves the user 
the effort of thinking up yet another meaningless secondary eddress. 


Perform DOPEN. Tests for DOPEN# filenumber, "name" and also the options 
for drive number, relative record length, unit number (i.e. ON UGor .U9 
with unit #9), and sequential cead/ write. [t sets up a command string and 
jumps to the normal OPEN routine. 


Perform APPEND. This command is not in some disk manuals. The command 
string puts .A after the file name and this sutomaticatly performs OPEN and 
sets the pointers to write sequentially on ot the end of the file. 


Get disk status string DS$, 
Get DS$ [jump table entry). 
with length held in $0D and pointer to start of (SOE). 
be tested with this machine~code: 

Lpy #0 

LDA (0£),¥ 

CUP #32 

BCS ERROR ; VALUE IS NEITHER O NOR 1. 


Perform HEADER. This has two forms, with and without a disk ID. As well 
as the usual validation, this command uses the ARE YOU SURE? prompt. On 
exit, DS id checked and ?BAD DISK ERROR appears it DS > 1. 


Perform DCLOSE. The syntax check permits cither DCLOSE or DCLOSE# file 
number [ON U8], or other device number. SDALI closes a numbered file; 
when no file number is given, all upen files of the correct device number are 
sought and closed by the routine at $DA1B. 


Set up disk record pointers. This is called from RECORD, Jt sends a five 
byte string to the disk which contains: 


ASCII for p| Secondary adaresa, [Ree no. lon 
$0353 $0354 “| __ 30358 


The default value for byte is 1. Byts is checked to ensure that only vatues 
from l-234 are accepted. : 


Perform COLLECT. COLLECT (in BASICS4, VALIDATE corresponded to this) 
has two forms: one has one parameter in the command string, the other two. 
depending on whether a drive is specifies or the default is used. 


Perform BACKUP. This checks that two drives are specified and an optional 
device number. it scts Y-#$16 und A-#$4 and enters the next routine, which 
is siso used by all the other disk commands excepl RECORD :- 


Send DOS command string frum buffer to disk. On entry, Y holds the offsel 
from D839, the table of dummy commands, and A holds the length of the 
dummy command: the true length of the commind, nfter the detnils have deen 
Inserted by DBFA, naturally varies with (for example) the length of a pro- 
gram‘s name, 


Perform COPY, COPY sends @ disk command string with 8 components, 
{rreapactive of its syntax (there are several valid versions). 


These routines set up a string in memory 
The vatue of DS can 














Perform CONCAT. Like COPY, CONCAT sends 9 command string with a fixed 
numher of variables, [n the ease of CONCAT this means 12 varlables, These 
are arranged (nee DASH FT.) In a string Ike thix: 


Cpa: 728 D2: F2, UL. Fl where BP and F are drive & fila aumbare, 


Note that thia string, and the others like ftare qoaeltimen entlad the ‘DOS 
Interface’ In Commodure documenta den, referring: to the fact that the dela 
whieh la nent to the dlsk hag te be in one of the atunderd forma to be 
procuseed correbly, 


Pa oe eR MY PERN A ce I ptr ete ar a 


Honea ym ret 


Programming the PET /CBM 


BASIC 4& 
$DAD4 


$DAFD 
$DB0D 


$D83A 


$DBS5 
$0866 


SDB99 
SD BSE 


SDBD7 
sO0BEt 


$O0BFA 


$UC4C 
$DC5? 


SDC6B 


$DE49 


SDEHT 


$i 20 


15: CBM BASIC ROMs 


-423- 


Put source file name inte DOS command string, This routine is called within 
DBFA when FI is encountered in the dummy disk command table, it places 
details, including the file's name, into the command buffer, which starts at 
$0353, and it sels pointers, i.e. (SFD), to this address. 


Store 2 parameters in adjacent addresses in the command string buffer. 


Perform DSAVE. This uses three parameters, sharing those of DOPEN at 
D83B. The filename and disk drive only ere sent in the command string. Note 
that the filename may be preceded by '@’ if save-with-replace is required, 
then the file is saved without the necessity to avoid °FILE EXISTS ERROR by 
first scratching the file. (However, ‘@ is reputedly not bug-free, and is to 
be avoided by the cautious user), 


Perform DLOAD. DLOAD uses similar output parameters to DSAVE. The flag 
in $9D is set zero for LOAD, not VERIFY, (This suggests that a disk verify 
command, say DVERIFY, could be written, identical te DLOAD but storing #1 
in the verify flag). 


Perform RENAME. DOS interface is KR Di:F2=DI:FL 


Perform SCRATCH. The DOS interface is 5 drive no. : filename (the. filename 
may include * and/or ?), This combination of parameters is checked by the 
parsing routine. To make erroneous del«ting of files less easy, 4 subroutine 
which prints ARE YOU SURF? (at DB9K) waits fur 'yes' or ‘y'. On exit, DS$ 
is read and - if it's been set - printed to the screen if the mode is direct. 


Check command is direct mode entry. [f it is, the equals flag (2) is set. 
Print ‘are you sure?’ and await reply. Only unshifted y or yes set the flags: 
C js returned clear if y or yes in entered, Otherwise BCS may be used to 
exit or jump past the unwsnted code. 

Print 7BAD DISK ERROR if in direct mode. 


Clear DS$ and ST. This routine leaves A,X, and Y unchanged, and sets ST 
and the length of the string DS$ to zero, Both are effectively zeroised. If a 
DS$ string existed already, its pointers in RAM are set to SFF28. 


DBDC prints it in any mode. 


Expands dummy variables to fill OOS command string in buffer $0353 ff. 

On entry. ¥ holds the offset of the start of the command string from$0839. 
A holds the length of the dummy string. Example: APPEND sets Y=n9,A=85. 
This corresponds io the data indicated for $D842; q.v. Evch dummy value, 
for instance Dt or EQ, is filled from thestoroge details in $0334 ff. 


Set file name length to value in X register; set pointer ($DA)=$0453. 
Process L,S, and W flugs. 


Parse disk BASIC command and store parameters. it is this routine which 
permits disk parameters to be entered in any order, A large loop processes 
the string, tooking for: 4WL RD ON token UT" or (, Anything else 
gives ?SYNTAX ERROR. $035K stores, bitwise, the parameters os they arc 
procesacd. So, if (suy) DLOAD#I#4 is entered, which of course is wrong, the 
fle number flug will be set on the second look at # and this will cauxe the 
"SYNTAX ERRO measage. The 7 bits of $033E hnve these meunings: 


ca 
MEANING OF BITS SET IN $9338 


“wit 7 fait & test 5 WIT 4 jarra fuer 2 jorrs [arr o | 
1) NU @ [WRITE [DEST MITE. | SOURCE DRIVE DEVICE # FILE @ DEST. FIDE FILE | 
a: 9 j ReAu XG DENT DR. | NO SOURCE DH. ed DEV. #| NO LPN | NG DEST, fan rine 


Get fle name, On ontry, CSIF) points to the adit of the string. UP bls dength 
exceeds $6, ur begins with Ta and exeveda (7, (he routine prints "SYNTAX 
ERROR, On mal, A holds length, X and Y abso hold CSTP) pointers. 

el parwmeter la range 0 259, The value dn retin i X andl in $62. The 
purameter 14 uden from BASIC (by CURGET) and evatuated; Hoi does tut 
beyin with G9, $f must be wilhly parenthedex,; so all these expressiony are 
avoopted if the mane bs rtyats CXeVD ond 22 sel CLeeVALCI Sey mel 468, 
Parwnelers auch as the tagdent file mamber are input wail thts. 


ISYNTAX ERROR, $0027 ILLEGAL QUANTITY ERROR, SDE74 7STRING TOO 
LONG ERRGH, $662? (BAD DISK ERROR, 


Fo pen og A LEE SR = EA FRR Ane Ate RMP 9% UNITE INA © SAEERANRIRT TS TB 
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SCREEN, KEYBOARD, AND INTERRUPT PROCESSING {$E0G0 ff), 


BASIC? BASICZ BASICH 


BASIC! 
SEIEt 
$E236 


$E269 
$ESD8 


$E270 


$E294 


$E2B7 


$E2FA 


$EI49 
$E356 
$E397 
SEJAG 
$HICA 


PPR EGE oR. oe PR RA He PT NICD MPR SIT Tm? ORS cn ARE REN A Le Tor eget 


BASIC2 BASIC4 


SETDE 
$E229 


$E25? 
$E250 


$£265 


SE29A 


SEZB8 


$E2F4 


SESIF 
SE34C 
SE32D 
$E396 
SESH4 


$E000 
$Eq00 
$E003 
$E006 
$E009 
sEoac 
SEOOF 
SEOS2 
$EG15 
Seats 
$E01B 
S$EOIE 
$E021 

SEQZ4 
$£027 
$EO2A 
$E020 
$E030 
$E033 
$EC36 


4O-col. 
$E000 


SEQYB 


$E257 
$EQ?7F 


$E087 


$Eaac 


SEQDA 


$E116 


SE1L67 
$E174 
$£1B3 
SELRE 
S$E1DE 
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JUMP TABLE FOR €0-COLUMN CBM ONLY. 








JMP E0a0. Bel + home cursor + initiatise input/ output. 


JMP EQA?: Input from keyboard buffer. 

JMP E416: Input from screen or keyboard via (SE9). 

JMP £202: Output 2 character via (SE8). 

$MP E442: IRQ servicing: BRK to moniter, hardware Interrupt 

JMP E455: Clock, cursor, keyboard, tape servicing. 

JMP E660: Exit from interrupt. 

JMP E051: Clear screen within window. 

JMP'E07A: Set CRT controller chip to fower/ upper case. 

JMP E082: Set CRT controller chip to upper case/ graphics. 

JMP £088: Other CRT controller chip settings. 

JMP E3C8: Screen scroll down. 

JMP E3E8; Screen scrolt up. 

JMP EuBE: Finds key from keyboard decoding table. 

JMP E6A?: Rings bell one chime. 

IMP £036: Store accumulator A in repeat flag. 

JMP €1E1; Set top left of scrofling window. 

JMP EIDC: Set tap right of scrolling window, 

Called from E02D, 

BASIC4 

8C-col. 

$E60F [Initialise input/ output Jeentions in VIA, PIAs, sect 
etock to zero, sect cursor, etc. 

$E€051 Clear the screen (within window in 2022). 

$E0SF Home cursor. 

SEOBF Po:ition cursor anywhere on sereen - $C6 holds 
horizontal, $08 vertical, positions. (In BASIC I, 
$E2 and $F5). 

$EQA7 Get character from keyboard buffer. On exit, the 
character is in A. The number of characters in the 
buffer is held in 89F ($0200 in BASIC 1}, and is 
assumed to be at least L. 

$EQBC Input from keyboard. Guts character(s) from the 
keybourd buffer, echoing them tu the screen and 
handling the curser position, finishing with carriage 

$ECDA return, If shift-Stop 7 Run is pressed, the keyboard 
buffer is erplaced by dL'*[Return JrunfReturn) in 
BASIC 4, LOAD[Return]RUN [Return] in BASIC<4. 

$E116 Input from screen or keyboard. This routine Is used 
by the INPUT routine whenever input is to be made 
from non-tape und non-lERE devices, Le. CHM's 
internal acreen or keybourd. The X and Y reyisters 
are preserved, When input is from screen, quotes 
and cuverse flagn ore tested for, and the cursor is 
updated, 

$E1GA Switch quote fing (0 to f or 1 to Q) if quote found. 

$E177 Pring screen character; update cursor, 

Set 80-churecter line indicatar. 
Convert 40 column dine te 88 character line, 
Jinek to previeus tine (when auctioning [DEL}, [LERTB 

SELAA  Advanee cursor; next ding if ead of windaw, 

$EIC1 9 Cluur ne tu end af witdaw, 

$ELD2Z Set windaw to fulleat site, 


- 
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BASIC1 SASIC2 


RO-col. 80-col, Print CBM ASCII character to the screen, This 
routine deals with all the cursor control and screen 
SEZEA $E308 $6202 $6202 editing characters. It takes cure of cursor process- 
ing and automatic screen scrolling. On entcy. Ahaids 
the character to be printed; note that both X end ¥ 
registers' contents nre preserved. BASIC 4. but 
onty the é0-column version, has an indirect jump 
enabling users' routines to intercept the output; it 
is via ($EB), 
There is different processing for direct mode ond 
program mode . 
SEJFF S$E3EC $6216 $6224 UNSHIFTED CHARACTERS: 
$E3FF $E3EG $8216 $6224 Carriage return, CHRS{13) 
$SEQ0A SE3F7 $6221 $&22F Ordinary ASCII character, CHR$(32) - CHRS$(127) 
SESI1D SE40A $6234 $E242 Delete, CHR${(20) 
SE444 $6831 $E25B $£26D Reverse, CHR$(18) 
$E948 $6437 $E26) $£273 Home, CHRS{19) 
$E4$2 S$ES3E $6268 $£287 Cursor right, CHR$(29} 
SE468 $E6454 $E27E $6296 Cursor down, CHRS$(17) 
$EZA0 Tab, CHRS$(9} 
$£2Da Erase beginning of line, CHR$(22] 
$E2E7 Delete line, CHRS(721) 
$£595 Scral! down, CHR$(25) 
$E59F Set top of window, CHRS{15) 
$ESAE Text mode, CHRS(14) 
$E5B7 Bell, CHRS(7) 
$E48F SEa7A SE2A% $E2F4 SHIFTED CHARACTERS: 
SEB2 S$E4X8D $€267 $307 Shift-return, CHRS(t41) 
SEQ9B $634C SEI74 SE177 Shifted ordinary ASCII chr., CHRS$(160)-CHR$( 255} 
$E9AD $6598 $€2CZ SE3t2~ Insert, CHRS{148} 
$ESt2 SE4FC $E326 $E35C Reverse off, CHRS{146) 
$SE52A $6513 $E&33D $E377 Clear, CHRS$(147) 
$ES1B $6504 $E32E $E364 Cursor left, CHR${!57) 
SEGE2 $ESCD $SE2F7 $€34B Cursor up, CHR${245) 
$E34G Tab set, CHRS{137)} 
$E393 Erase to end of line, CHR$(150) 
$—sco Insert line, CHR$(149) 
$ESD6 Scroti up, CHR$(353) 
5ESE2 Set bottom of window, CHR${ 143) 
$ESF1 Graphics mode, CHR5(142) 
SESB7 = Shift-bell (=betl}, CHR$(135) 
$€3BD Escape and shift-escepe, CHR$(27) and CHR$(155} 
$P530 $2519 3E343 $E3A3 Cursor down. 
$E548 $E52P $6359 $E386 Process Retum. 
$6559 $ES3F $6369 $E&3C8 Scroll screen up. BASIC i and 2 are identical; and 
BASIC 4 (40 column) almost icentleal to these, But 
BASIC 4 (90 column) Is rewritten (1) fo nilow the 
sereen to seroll ups (4) To inchude ao pemine ferture 
which stops sere acral: Ci} To peesent Che TERE 
‘LOR charneter being sent. whieh all othic HASTCS 
do when the sereen scrolls (because one of the VIA 
fliners, EMT1/ EBL2Z, 8 used to time the delay loop 
when RYS jf preaned!) 
Note that HASIC 4 with 40 columna still basa thls bug 
in tho f¥RE. (The remedy, of course, ix simply to 
avoid acrotiing Une aorean), 
. 
TN ery oe ene tee a LLY Somme ef REM SERIA YS RI SRA Hn MR RECN OAS © FS oS 


BASIC4 BASICS 
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BASIC1 BASIC2 BASIC’ BASICS 
40-col. @0-col. 


$E3E8 Scroll screen down. 
SE5CI $ESAl $E3C9 $E40B Check for [Reverse]; if pressed, .5 sec. delay. 
$E5C8 $S$ESA8 S$EXDU $E412  Half-second datay, 
$E5DB Start new screen line (called by E269). 
SEG04 Action ‘Insert’. 
$E617 $ESCC SE3E2 Open a space in a line with ‘Insert’ 


SE66B $E61B $E942 $E442) MAIN INTERRUPT ENTRY POINT FROM IRQ, 


Save A,X, and Y. Then test for BRK or hardware 
interrupt. An indirect jump is performed according 
to the result of this tesi. 

BRK. ($92) holds the vector; on setting up BASIC 
this is pointed to the Brouk entry-potnt of the 
moniter. (BASIC Ll: ($021B} points to $0000, giving 
WLLEGAL QUANTITY ERROR unless a BASIC USR 
function is operative). 

Hardware, ($93) holds the vector; on setting up 
BASIC this points to the [RQ servicing routine. It 
is this indirection which makes possible user inter- 
ception of the 60-per-second interrupts.* In BASIC 1 
the vector is in ($0219), 


$E685 $E62E $6455 $E455 IRQ servicing routine. Unless the interrupt is 
masked by Stl, or the veetor is ultered not to point 
here on 46 interrupt, or the interrupt is programmed 
not to take place, this routine is performed sixty 
iimes euch second. * 


$SES85 $E62& $E455 $E485 Update clock. A single JSR call updates the clock 
see $FFEA). 8032 BASIC has a loop to add 1 jiffy 
in every 7, This also checks for the Stop key, 59 
pointing ($90) to the following routine - ($0215) in 
BASIC 1 - disables the Stop key (and stops the 
elock ). 
$E683 SE63i $6458 $8458 Cursor finsh. Several flugs are used: 
$A7:I1£ non-zero, the cursor won't flash. 
$A8: Counts to zero; then reverses the cursor. 
$A; Holds the actual character, not ity reverse. 
$AA: Flag = 0 or } to indicate flash/ not flash. 
$E4; Repeat Mug (8092 only). When>127 countdown 
constunt = #2 so flushing is much faster. 
SE6BO $EG4D $E474 SEA7A_ Prepare for keyboard scan, This sets ‘key image’ to 
- ‘no Key’, ‘shift key image’ to off, clenrs the four 
bity 0-3 in E10, performs 1/Q funetions (c.g. turns 
off the enssette motors) - celuity vary with HOM - 
and load X with 4$90, (8 cucimal;, rcady to sean 
the 80 characters in the 10 by § decode table, 
$EGF7 SES8E $£4B5 $E4CD Loop which scuns keyboard.” Each key sets T bit low 
in $E8L2, whieh therefare holds only 4PF, aFR, aFD, 
#FD. APT, aE, SDE. RP, or #70. flowever, it in low 
only when $EHIG heldy (he correct Crow! - ab value 
from 09. Thas 40 characters are pos cihte, most of 
whieh are yeed. in addition, the shift hey may be 
pressed, approximately doubllay Hie number of 
keybonrd characters avaflabb:. SEHTO bs incremented 
durlay ta loop, on ext boholda 9 in ite rdgtin fit 
hits, rod this defauit value by in [ores wher Seal 2 it 
lonied inte A; this in why characters dike 9, apart 
fn non #092 machines, aed; 9,8. ete. bn #032, re 
eften dad in non ASCH wouya. 


29" wcreen CAM‘ a Interrupts occur 50 tiace par mecund. 
9” dehounce routing (a saall tonp) ta included tn tne keyboard scanning routine. 


eee Sere oy 


HES egg mM em a IRR EIS caper ener 6 oe TN aan Corrente arr oe: 


| 
| 
| 
| 


 rpepemeat renee = tt ERAS 4 me, 


ee i oe eee 


ee a iepmpecty ee. Sh ro 
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BASIC? BASIC2 BASIC4 BASIC4 
AO-col. 80-col. 


9E714 SE6C2 SE4E® $E504 Process new key. The new ‘key image’, in $Ab, is 
compared with the previous key. in $97. If they are 
the same (both may be #FF, signalling no key, or 
both may hold 1-80, corresponding to a character in 
the table). 

$E546 Reutine to erase graphics characters by unsetting 

the high bit which shift may have set. 

Put new character into the keyboard buffer. All 

BASICS except the $032 BASIC 4 delete the keyboard 

buffer if more than LO characters are now present, 

this includes BASIC 4 in the 4016 and 4032. The 
$032, however, preserves the current buffer, and in 
addition has a variabie iength buffer, where the max- 

. imum number of stored characters is PEEK(2z27)+1. 

$EGTE SEGE4 $E600 $E606 Return from interrupt; recover A,X, and Y. 

$E7AC $EGEA. $£606 $E606 Poke contents of A into screen. Example: when A 
eontains 42, b or B depending on the ROM mode is 
printed on the screen. On exit, Y holds the cursor 
position on its line, Note that BASICs 1 and 2 have 
a loop which awaits the retrace interrupt before 
printing. This prevents 'snow' (with the old PETs} 
and also slows the print. {Some other machines, e.g. 
Sharp MZ-80K, share this old PET feature). ' 

$E6A4 Ring bell twice. 

SE6GA7 Ring bell once. If $SE7 holds #0, this is turned off; 
otherwise, it is a delay constant. A table of 7 values 
plays the chime; these are #OE.a1E, #3E, #7E. #3E, FILE, 
and #0E, 


KEYBOARD DECODING TABLES. 


Table of 80 ASCII characters for BASIC 1, BASIC 2, 
and 4016/ 4032. 


SE7T2C SE6D6 SEG4FD $8563 


$E75C SEGF&8 S$E60B 


CONTENTS OF: 


$£810 __ $eal2 (=59410) ee 
#98F | #SDF 











MOYSES: 2. The shift keys are detected agparalely and aig labsiled ‘sight’ and ‘ieft! 
hur. . 
It. ft can be aeen Prom the tally chat WALT 30410,4,4 fnudem untii space of 
shifl-apad Is prenaet, WAIT SUU0,3,) welta until RYE or RYSOFF in pronacd, 
WAIT $9419,5, 2549 walla for elther space of reveras, and ae on, 
fil. The order @f charurtera ie the saan an in (he ROM tadle, 


fe pant pen rae ee ee re Oe mR em RM te ee oe SPINE ee mE 
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BASIC1 BASIC2 BASICS BASICAa 


$6810 
($9408) 


40-col. 80col. 
SEGDE 
CONTENTS OF: 


‘$EB12 (559410 
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Table of characters for the 3032. Note that tabled 
values with the high bit set have no shifted equival- 
ents; they correspond to keys like @ and |] which are 
marked with a single, non-alphabetic, symbol. 





weve | wsor | aspr | #ser | sr? | 


stop | 9g 


eee 
ROWE . SPACE | x 





cieere ae 























SETRC 


SETD4 


SE819 
SEG20 
SEguG 


im tee oe ASE ETT ORRIN Pe a Arn AE RE ae UM I Ret Si ee 








: 4. @ beside a character means that it has no shifted equivalent. Hence sume 


characters, ¢.g. ail the numerals, appear twice. 

ii. Note that the contents of E812 (=59410) when ERLO holds -@ are not the 
pane an those for the earlier ROMS and 40-column BASIC 4. This is the 
reason far the use of different acts of keys vhon slowing (and pausing) 
acreen scroll. 

114. Tha quantities {n square brackets appear to be unused ASCII values. 


SE74a 


SE76I 


SE6TO 
$E€620 
$Eeuo 


SET2A 
$E73C 

SE65B $E755 
SET6E 

SEG74  $E721 


Two tubles of 18 constants each for CRT controlier. 
Lower case mode (switch-an) and upper case. See 
Chapter 9 on this chip. 

Table of 25 low Dytes which mark the ond of each 
serven fine. 

Tuble of 25 high bytes marking the start of each 
screen line. Thase are held in RAM in 40-column 
machiner to allow alturations for double-lenyth lines. 
Message tabie. LOAD [Rcturn|] RUN [Return] or 
@L"* {Return} run {Return}. 


SYSTEM INPUT/ OUTPUT MEMORY MAP. 


$E81G $EaI10 
$E820 SEB20 
$Eb40 SES4O 

SEa8O 


PIA (Peripheral interface adapter) 4}. 

PIA #2. 

ViA (Versatite interface adapter), 

CRT controfter. 8032 only. 

ALL these iddrenses are taconpletely decoded, 


cee em A Ne AT eam an eae es emp 


Car a Pe ee A RD CRA A AP aE i 
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BASIC1 
$F000 


$FOB6 
SFOBA 
$FOBC 


$FOE4 
SFOFI 


$Fill 


$F12C 


$F 132 


$F13P 


£B SAU 


aes 
| mete RE A rr oT 


BASIC2 
$Fooo 


$FOBE 
$FOBA 
$FOSC 


S$FOE2 
SFOEE 


$F10D 


$Fl2B 


SFILO 


$F 195 


$146 





$FOGG 


$FOD2 
$FGDS 
$FoD7 


$FOFD 
SFiO9 


$F128 


$F183 


$RL4gH 
$i1si 


SFIas 


SFIS 


Fe RRP A ME ma atm re 


TT ee, ORT 
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Table of messages for file handling. These are: /ton many 
files/file open/file not open/file not found/[Rtn ]searching / 
for /[Rtn]press play /& record/on tape a/[Rtn Jload/[ Rtn} 
writing /([Rtn ]verify/device not present/not input file/not 
output file/[Rtn]found /[RtnJok{RtnJ/[Rtnjready. {Rtn} /. 
BASIC 4 has these two messages in addition: /[Rtnjare you 
sure ?/[Rtn]? bad disk/, 


Send ‘'Taik’ on JEEE-458 bus. 

Send 'Listen'. 

Send 'Untalk' or 'Unlisten'. 

This routine, with three entry points, handles handshaking 
on the dus before falling through to the next routine, where 
its prepared character is sent on the dus and causes the 
device to talk or listen or otherwise respond. What happens 
is ag follows: the current device number (e.g. 8 for a disk) 
is ORed with the value that A held on entry to this routine, 
and which was pushed on the stack. There are four possible 
values: A=#40 means ‘Talk’, A=#20 means ‘Listen’, and A-#3F 
and #3F mean ‘Unilisten' and 'Untalk'., Of these, two are set 
on entering the routine at the appropriate entry points; while 
'Unlisten' for example requires LDA#SF/ JSR FOD7. A is ORed 
with the device number and placed into the IEEE buffer in 
$45; it is sent from here by the next routine. Just before 
entering it, ATN (attention) is sect low, f.e. true. so that the 
byte is undersiood as 4 command. Consequently, after this 
routine, ATN must be set high again, Nole that @ character 
in the IEEE buffer which has not yet been sent is taken care 
of by the present routine: $A0, the output flag. is non-zero 
if a character is waiting in the buffer $A$, and if this situalioa 
applies, the character witl be sent before processing the [EEF 
command. BASIC L's IEEE buffer is location $0222. 

Puts A into the buffer, sets ATN true, and sends the byte. 


Send one character on [EEE-488 bus. The character which is 
sent is the one previously stored in the buffer. The sequence 
of events is this: (i) Sets Data Valid out false; (ii) Tests for 
activity on the bus ; if nune is found.ST is set to #40, to 
signal a device not present error. (ili) Loads the byte from the 
buffer, reverses it, buenuse the [EEE convention is the reverse - 
of ASCI, and stores the result in $6822, the output register. 
(iv) Loops while NRFD (not ready for data} is true; then sels 
DAV (data valid) truce, (vj Sets the VIA timer und loops as 
long a4 NDAC (not data xccepled) is true - t.e. while the 
byte hus not been accepted by the device. If the timer reaches 
65 milliseconds, ST ia set to #1. This is a "Write time out’ error 
if it occurs. BASIC 4 has on optionnl override to cuneel this 
mechanism. (v) Ont velic is set false; the output register 

ig loaded with WEF, the [EEE equivalent of a null byte, 


Send ona cheracter and clear ATN, This Is typlenlly used to 
dend TERE commands @iuch ag Uhe secondary actress, #8000 + 
0-15) when ATA is brue and one command oily is wanted, Lob. 
used by louding Aowith the character, hen entlingg thts sub 
rogline, which stores Aim the TLER buffer, calls the routiae 
immediately before thig ane, thea sots altention biyh Chiles. 
Set AYN ialyh (fotse), 

Uptionnal timeout override wilh Stap key lest). 

Fiag errors inte ST. ST $ Cwrite time outy, ST 22a Cdevlee 
hot presenth, and ST 2 Cread tine out) are procesivd here 
In theres rudtines, 


Clear TREK eoutrol ines, 


Se a RE Eg Fe sree Simm a ae me rie Ram me = 
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BASIC? BASIC2 BASICS 


$E70E 


$F15B 
$F167 


SFI7A 


$FI7E 
$F187 


S$FICC 


SFLD6 
$FIDF 


SFIFS 
$F202 


SFU27 


OEE TREY, rt TR nm men setae AAT SAL ATR RICE cd SRT me PM eRe meme rie Ae = 


$FIS56 


SFl64 
SFIG6F 


SPIT7F 


$F183 
SFsaC 


SFIDi 


$FiD9 
SFIE1 


SFIFG 
SFLIFF 


$F228 


$Ft8S Print message from table starting $F0Q0. This is always called 
from F579/ FS6E/ FSAD which ahorts files, prints Return and a4 
query, and follows the message with ‘error’ and an optional 
finenumber if it's in a program. The Y offset controls the 
actual message. 


Send byte; then set NDAC (not data accepted) true. 


Send [EEE character. /f the buffer cuatuins a character at 
present, that character iy output, and the contents of A put 
in the buffer. Otherwise, the contents of A are put into the 
buffer, and the output fing reset fron 40 to #FF. In either 
case, on exit flag $A0 holds #fF, and buffer SAS holds A. 
(BASIC 1: $621D and $0222 respectively}, 


Send 'Untalk’, BASIC 4, unlike BASIC<4, seta ATN true 
before entering FOBC/FOBC/FOQD7, This corrects 3 bug; see 
Chapter 14. 

Send 'Uniisten', All ROMs function identically, 


Get one character from the 1EEE-498 bus. The byte is return- 
ed in A, This routine uses the identical timing subroutine used 
to output a character; BASIC 4 aguin hus the option of over- 
riding the time out. ST=2 if this is not done and the device 
fails to return a byte within 65 milliseconds. The sequence of 
events is: (i) Seta NDAC (not data accepted) true, and NRFD 
(not ready for data) false. (ii) Waits until DAV (data valid) 
hus been set true. ST is set =2 if the wait exceeds 65 millisec- 
onds (but the timer can be overriddan in BASIC 4, by poking 
S03FC (1020 decimal) with a ‘negative! number). (iii) Sets 
NRFD true, (iv) Checks EOI: if found, ST is set to #40 (64 
decimal) to indicate end-of-file. (v) Takes the byte, reverses 
it, and saves this value on the stack. (vi} Sends NDAC false, 
to indicate that the data was acecpted, then waits for DAV to 
become true; finally, NDAC is set trie again, and the byte is 
recovered from the stack and placed into A. 


SFIS 
SPI9E 


SFLAE 


$F1B9 
$FICcO 


$F205 GET s byte. The jump table entry for GET - which gets a 
character into the accumulator without assigning it te a name- 
jumps here. The oper:tion ef this routine depends on the 
contents of $AF ($0262 in BASIC 1) which holds the input 
device number, for exumple t for cassette #t. 3 for the sercen 
ang 8 for a disk unit. If the device number is 4 or more, then 
Input from the [EEE bus fs assumed, and the previous routine 
is uscd, Otherwise thereare three other pogsibililies. 

GET from the keyboard buffer. 

INPUT @ byte. The jump table entry for INPUT ia here. Most 
of the logic is identical to GET - hence its position here amid 
CET. The difference is that input from device # is taken from 
the screen, 

GET from the screen. 

GET from cussetie #1 or cassette #2. This routine Ia in two 
pacts; the first rents a byte, and the next byte, 40 that ST 
May be set te #40 (64 dec.) on end of Mle, simulaneously 

with returning ihe tiat byte, The other routiee in a subrootine 
which fa culled by Une first routine of the two, Tt advanens the 
buffer painter tnd, if neeminiry, lowdse anather buffer of data, 
GET from aa (KEE devies, This enlls PIBT/PIRCIFICO, but 
only if ST 0. If the slitus byte holt any non aero value, 
Une ThE rouline fa nat eailud; dasteacd, the carrlayge return 
character (#0D) da put inte the accumulator, CHASIC Lb lacks 
(his fealure. tt returns the value of ST Instered), 


SF20D 
$F215 


$F228 
$F233 


SF2Z5C 


a le ae a 
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BASIC? BASIC2 


$F230 


$F23D 
$¥F24d3 
SF247 


$F236 


SF2A4 


$F299 


SFXAB 


$F2B9 


$F2Ca 


$F2D5 
$P2E1 
sF30T 


$FI0A 


$F232 


$F239 
$F23F 
$F243 


$F26E 


$F284 


$F28D 


$F299 


$F2A9 


$P2B6 
$F2C2 


GF2E1 
SP2E4 


” 
oo ry are Cer 8 an rn on: REE Ve re 
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BASICa 


$F266 Frint one character ta any device. The kernel jump table 


command $FFD2 jumps toe this address. Like the previous 
GET/ INPUT routine, its operation depends on a single byte 
which tells it which device is to receive output. This location 
is the current output device number, held in $B0, or $0264 in 
BASIC 1. The accumulator contains the character Lo be output. 
So if $B0 hoids 3, LDA #$93/ JSR $FFD2 clears the screen. 
PRINT to screen. ; 

PRINT to device #93. Uses FEEE output buffer rouline. 
PRINT to device #3. This writes to tape. The tape buffer iS 
one byte, location $4 (SE9 in BASIC 1), from whence It is 
moved to the buffer appropriate to the cassette#, and, when 
this buffer is full, as measured by the pointer in $D4 (SFL in 
BASIC 1), the buffer is written to tape. Note that the line- 
feed character, with ASCII value #0A (10 decimal) is trapped 
by this routine and cannot be written 46 data to tape by 
this PRINT routine. ; 

®NOT OUTPUT FILE ERROR if ‘output device’ is #0 (i.e, the 
keybuurd), 


Abort ull files and I/O activity. This routine {i) Sets the 
number of open files flag to zero (i.e. SAE or $0262 in BASIC 
1}, (ii) If the output device number exceeds 3, 'Unitsten’ is 
sent; and if the input device number exceeds 3, 'Untalk’, 

The files are not CLOSEd, so files being written to may be 
incompletely processed. and there is some risk of later corr- 
uption with disk files, The routine now performs;- 
Restore default input and output device numbers. This simply 
puts #3 into the output file flag and #@ into the input device 
number flag. ($80 and $AF respectively - or $0263 and $0268 
in BASIC 1). 


Search tadle for logical file number. A holds the logical file 
number on entering this routine. [f the file number exists in 
the table, the ‘equals zero’ Z fleg is set, and X holds the 
displacement from the stuart of the table. 


Set file data from position in table. On entry, X is the offset 
from the start of each table - as found by the previous rout~ 
Ine. The logical fe number, device number, and secondary 
address are all tnken trom thoir respective tables and put into 
$D2,3D4, and $03 which are the current values. (In BASIC 1 
these locations are S&F, $F 1, and $F0. 


Perform CLOSE. $FFC3 in the ‘kernel’ jump address table 
comes here, The slurt of this ruutine fetches the parameters 
used with CLOSE and stores the logical file number, device 
number and sccondary address in $D2-$D4. [¢ uses the pre- 
vious routines for thls. 

$D2-$04 are assumed set up; X holds the position of the file 
data in the three tables, Now the routine branches: 

CLOSE devices #1 and #2 (Le. cassettes), This involves 
writing a zero byte on the tape, and optionally an end-of- 
fape ‘header’ hulding the marker value @5, 

CLOSE deviews #4 stal greater Coe, all TERE devices). 

Théw ‘Untistenat the device; Lhen exesutes the following :- 
CLOSE devices #0 and WI, and remove Xth item from al! three 
Me (ables. Thig ds carried out by decrementing the flag 
Holding Une number of open files; then tranaferring the 
previews lint fie details into the Xth ponitian, effectively 
deleling the file records, 


$F26D 
$F273 
$F277 


$F2A2 


$258 


SF2Ci 


$F2cD 


$F2D0 
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$F339 


SE33F 


$F362 


SF366 
SF36F 


SFITE 


SF37B 


SF37E 


SF38E 


SFI9A 
$PISC 


S¥IA5 
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S$F315 


$F322 


SF326 
$F32F 


$F349 


$FI52 


$F355 


$F36D 


$F378 
SFOTA 


$F387 


$PI95 


$F3a9 


SF3S6 


S$F35A 
SF363 


SF37C 


$F38C 


SFI8FP 


S$FIAT 


$F3R3 
$FIBS 


$FIC8 


$FaD4 


Test ‘Stop’ key, $FFElin the ‘kernel' jump tebie comes here. 
This calis an immediately preceding subroutine, then jumps to 
the start of the BASIC STOP and END routine. If the zero 
flag was sect, a dreak occurs: otherwise, Stop wasn't pressed 
and BASIC continues normally. Note that all ROMs test for 
WEF in $5812; Stop is one of the few keys decoded in the 
same way by BASICs 1-4. [t aiso follows that SYS 62275 can 
be used to test for Stop even if that key is otherwise disabled 
by a change in the interrupt vector, 


Send file message from $FOOOff if in direct mode. RASIC 1 has 
an apparently unreliable test for direct mode; BASIC?1 uses 
a short subroutine. The message printed depends on the 
value in Y, which is treated as an offset. (E.g. when Y=#E, 
the message is FILE OPEN). 


Load a BASIC program or other RAM imaqe. This is not the 
BASIC entry point; this routine is called after the parameters 
have been input, and before the pointers are set after the 
load. It handles the process of fetching data into memory. 
(tn BASIC 1 it is not fully separate from LOAD, but inter 
BASICs have it as a separate subroutine). The device number 
a5 input with the parameters (c.g. LOAD "HELLO",2 sets the 
device number parameter to 2, i.e. cassette #2) determines © 
the course of this routine:- 

9SYNTAX ERROR if device is #0 or 43. 

Load from any IEEE device. A progrum name is assumed: its 
length is stored in $Di and {$DA) points to its start. [f SD! 
hotds zero, this routine prints "SYNTAX ERROR. Several 
messages follow, each using a test for direct mode (see last- 
but-one routine) so the sereen layout is retained with a loud 
from within a program. The IEEE is ‘Talk'ed and the secondary 
addresy sent, now the actual loading vegins: 

Fetch data from device. Note that BASIC | always sets the 
starting address to $0400. BASIC>L uses the first two bytes 
from the bus to set the low end high bytes respectively of 
the starting address. in addition, BASIC 4 has a read time 
out defeat at this point, presumably to allaw for disk read time. 
Print LOADING or VERIFYING if in direct mode. [f the load 
flag ($D4) =0, lund is signatied; 1 is used for verifiention. 


Loop which loads data into RAM or verifies data already inRAM. 
Firstty, an inner loop handles the input of 1 byte; it testy for 
Stop and repeatedly loops until no time aut on rend error is 
shown In ST. Secondly. the routine branches, depending on 
whether LOAD or VERIFY is being performed: 

VERIFY, Compare byts with memory; set $T=#$10 (16 dee) if 
the two don't match, Then continue, 

LOAD. Store the byte in RAM. Then continue: 

Increment load address (SFB) or ($67) In BASIC i. Check 
bit 6 of ST (EOI) und continua with oop if this in p. 

Seta the end address whan LOAD of VERIFY is Snished. 
i.e. transfers the ineremented ($FB) contents into ($C9). 
Atso Untke and clears channel, 


Load from cassette, This routine is in three parta: the first 
seth pointers ta ane of the qusxette buffers Cahich ane is in: 
dicated by the device number), and printy various mesmedyfeds 
{f the mode la direct. and olga wits for the enasette key to 
be preased, The second purt finda the header: thia ia simply 
a bulfar which containa the program ar file rune and some 
other data, The Inied part is ihe actual losding ¢ verifylog 
Into RAM, BASIC 1, again, is more confusingly written than 
later ROM ruviniona, 


ee ee 
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$F&22 


$F421 
SF4URE 


$F433 $F93E 


$F45C $F460 


SFa62 $F&66 


$F47D 
$F482 


SFa9s 


$F47C 
$F483 


SFuUS4 


$F4aBB 
$¥4C4 
SFACA 
SF4aCF 
$Fag3 


$F4B7 
SF40B 
SFACA 
$F4C9 
$FACE 
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$F460 
$Fa6o 


$Fa7D 


$F49F 


$FYAS 


SF4BB 
$F4C0 


SFaps 


$FaF6 
SF4FD 
$F503 
$¥508 


$FS0D 
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Perform LOAD. $F3C2 from the ‘kernel' jump table comes here. 
This puts @ into the load/verify flag. 

Entry point from VERIFY; flag is loaded with 1, (Note: this 
value must be 1; it cannot simply be a non-zero quantity, as 
it is used during the processing). 

Now, three fairly distinct operations are carried out. First, 
the parameters are fetched from BASIC and the current BASIC 
pointers are saved. The routine waits until no key on the key- 
board is pressed. Secondly, the previous routine is called to 
LOAD or VERIFY the program. Thirdly, on return, there may 
be a ?LOAD ERROR, a READY. message, or, if LOAD or 
VERIFY took place from a program, BASIC is warm started, 
retuining the previous variables (up to a point-see Chapter 

5 on LOAD}, 


Print SEARCHING if in direct mode. 
If length of string is non-zero print FOR and 
print name string. 


Print LOADING or VERIFYING if in direct mode, 
message depends on the LOAD / VERIFY flag. 


Fetch parameters for LOAD, SAVE, or VERIFY. The para- 
meters are taken from BASIC or from the input buffer, and 
stored. In BASI[C>1 they are: 

$Dislength of string and ($DA)= pointer to start of string. 
$D3- secondary address. 

$D4=device number. 

In all BASICS these default to # length, # secondary address, 
and device #1 (cassette #1). 

Check for comma and evaluate parameter 0-255. The result is 
returned in the X register. 


Send name string to IEEE-488 bus. This assumes that the 
secondary address and length have been put in $D3 and $D1. 
The device is sent 'Listen' and ¢if it responds) the string. 
Print 7DEVICE NOT PRESENT ERROR. 

Send name string (if it exists) and close IEEE channel. 


Search for a named tape header block. This calls the routine 
to find any header, i.e. thy next header on tape. When 4 
header js found, its name (which starts at position 5 in the 
buffer) ls compared with the stored name at ($DA). This 
Process continues until end-of-tape, or until the tape runs 
out, or a match is found, In which case A holds the length 
of the name in the header (which may be shorter than the 
name searched for). 


Perform VERIFY. $FFDSH in the 'kernel' jump table comes here. 
Check bit 5 of ST. 

Print ?VERIFY ERROR and exit. 

Print OK, (not from within a program). 


Fetch parameters for OPEN or CLOSE. This routine fetches 
the prramceters corresponding to this sehema: OPUN arithmetic 
expression [, arith, exp. [,arkh, exp, [, atring exp. \}). 
The first of these, which is the logical file number, in com- 
pubsiory; the rest are optwnal. In HASICOL, thes are the 
locotiona which ara set: 

$Be lagleal fle number. 

SVt-lenyth of string, (SPA) its pulnter, SDI defaulls to @. 
$D4edaviee number, Oufuult «1. 

$Dd-secordary address. Defnult-0, or #FF with ERE device, 
BASIC | equivalenta are; SEF, SEE and ((4F9), $6 i and SFO, 


The actual 
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bFS79 


bF58B 
bF592 


}F5AE 


5FSAE 


$F5E3 


$F632 


$F64D 


$P687 
$P67D 


$P50E 
$F516 


$F521 


$F526 
$F52D 


SF597 
$F539 
$F549 
$F556 
$F559 


$F569 


SFS5G6E 


$F583 
$ESB8A 


$FSAG 


$F5DA 


SF5EB 


$P625 


$F83c 


$F656 
$FH6C 
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$F54D 
$F555 


Exit from parameter-fetching subroutine if end-of-statement. 
Check the existence of a comma followed by any character 
except cofon or end-of-line. 


Perform OPEN. $EFCO in the ‘kernel!’ jump table comes here. 
‘This routine first uses the subroutine at F433/FACE/FSOD to 
fetch and store the parameters, If the file number is zero, 
"SYNTAX ERROR is printed. {f the file already exists, 
°FILE OPEN ERROR is printed. STis made equal tu zero. 

If there are already 10 open files, the routine prints ?TOO 
MANY FILES and exits. (BASIC | has a bug at this point 
which causes an infinite loop - see F53B to F547). 

Store the new logical file number, secondary address, and 
device number to the tables at 0251-025A, 0265-026E, and 
0258-0264, 

lf device number is $ ur 3, RTS - i.e. nothing more with 
screen file or keyboard file. 

{EEE device: send program name or string to JE£ZE bus. 
Cussette #1 or #2. The processing here depends on the sec~ 
ondary address. If it is the default value of #, tape is read: 
otherwise it is writtcn to, 

OPEN to read named file. (After WAIT: PRESS PLAY... and 
SEARCHING ...). 


Print ?FILE NOT FOUND ERROR IN ... 


OPEN to read unnamed cassette file (i.e. the next on tape). 
OPEN for write, This writes a header onto the tape; the 
header type character is #4. Also the secondary address, or 
#BF where this is 6, is stored for reference when CLOSEing 
the file - it indicates whether an end-of-tape block is to be 
written or not. 


$FS5&S 


SFSAF 
$F56C 


$F576 
$P578 


$F5a8 


$F595 
$F598a 


SFSA8 


$FSAD ang exit. Aborts files. 
$F5C2 
$F5C9 


Load next tape header. This saves the load/verify flag on 
the stack, rends a block, then continues to read blocks 
unless the first character in the buffer is 1,4, or 5. These 
signal program or RAM image header, data header, and, lastly, 
when #5, an end-of-tape header, In either of the first two 
cases, FOUND with 16 characters maximum of the name is 
printed, if load is in direct mode. On exit, A holds #0 if an 
end-of-tape header wns read; otherwise, A holds #1. 


Write tape header, On entry, A holds the type-of-header byte 
(nee previous routine’s totes). Most of this routine ig then 
occupied with putting dats lito the buffer. ($D6) points to the 
atart of the cuasette bulfer, which is filled with spuces by @ 
short loop. The following bytes are now storad in the buffer: 
TYPE FLAG [LOW THEN HIGIL| LOW THEN HIGH | PROGRAM NAME; 
{#1,04 OR #5)| BYTES OF (FL) | BYTES OF (C9) | LENGTH=UP TO 3D) 
Seta the buffer Ktart and end addread and writes to tape, 
(FB) and (C9) point to the low byte and high byte of RAM 
area to be written. $Cu holds a timing value, #649, controlling 
the amount of tape to which a tone is written bofore the hosder 
proper la written, * 


Tape address subroutines. When reading a tape, thia firat 
subroutine trkes the start and end addressey from the bytes 
foaded fram the header, They are pul inte (FB) and (09). 
the start gid and addressen respectively. BASIC ft: CFT) 4a(F4h 
Suts pointer (D8) = G27A ar 930A for davies €or wa. 

Sots (PB) and (C9) from (6) - sel by the previous routine- 
to (D4) and (DG) + #800 €192 decimal), 

Sets (FH) and (C4) lo start and end of HASIC. Uned in LOAD 


$F5ES 


$F619 


S$F62A 








$FG64 


SFOTH 


$F59% 
$FEAQ 


$F6CC 
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SFG695 


$F69E 


$F6B1 


SFEBS 
ve $F6CO 


SF6F6 


$F70D 


SF736 


$1736 
SPTAK 
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$F6aa 


$FE9E 


SFGA4 


SFGAS 
SF6B3 


SF703 


$F7iB 


$F729 


$729 


SF7Au 


$F6c3 


$F6DD 


SFEEO 


$F6E7 
SFGF2 


$F742 


$FTSA 


F768 


SF7GA 
SP7TA 
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Perform SYS. S$FFDE from CBM's 'kernel' jumps here. The 
routine evaluates any arithmetic expression, rounds it down 
and loads the result into ($11), if its value is within the 
acceptable range for SYS (0-65535). It performs an indirect 
jump to ($11). 


Perform SAVE. SFFD8 from CBM's ‘kernel’? jumps here. This 
routine first inputs the parameters from BASIC by calling 
F433/F43E/F47D. This stores the string and its pointers, the 
device number, and the secondary address. Then EASIC's 
start address and end address pointers are transferred to 
the SAVE start and end pointer addresses. Alf the parameters 
are now sei up for SAVEing, 

This is the next entry point, which is used by the monitor 
and may be part of a user routine: all that's required is 

the parameters for device number, bottom and top address, 
pointer to name, Iength of name, and secondary address to 
be set, as though the previous two subroutines had been 
called. Note that the topmost address is not saved; with 
BASIC this doesn't matter, but machine-code dumps from RAM 
may very weli crash if they're truncated by a byte. 

°DEVICE NOT PRESENT if device number is #0 or #3. 


SAVE to IEEE device. This performs the following steps: 

(i) Secondary address is made t. 

(ii) 2SYNTAX ERROR if program name has length zero. 

{iii} Send name to IEEE and secondary address. 

(iv) Make (C7) and (C9) the start and end addresses of the 
part or RAM to be SAVEd. 

(v) Send the contents of C7 and C8, On LOAD, these are 
used to determine the address frum which bytes will be 
stored in RAM agzin. 

(vi} Characters are sent one by one until the lower pointer 
has been incremented to equal the higher pointer. Also 
Stop is tested; so SAVE may be aborted by the Stop key. 

¢vii) The channel is cleared and the device Unlistened, 


SAVE to cassette #1 or #2. This performa the following steps: 

(i) Set buffer pointer to 027A or 033A depending on device #. 

(ii) Print PRESS PLAY AND RECORD ON TAPE #1 or 2. 
Wait for cassette keypress - hopefully of the currect keys. 

dill) in direct mode, print WRITING and name. 

(iv) Write the header with type character = 1, 

(v) Write the contents of RAM from the lower to the higher 
address. 

(vi) If the secondary address hus bit Lon, t.e. secondary 
address wan 2, write «nother header with type chiracter 
+ 5 to signify an end-of-tape marker, 


Update the clock / Save Stop or Reverse key. $FFEA in the 
‘kernel! jump (ible calls this routine. In addition to adding 1 
to the clock (usually), this saves the contenta of $E 812 In a 
speclal location, $916 or $6209 in HASTC 1, This ls waxed ns 
test fur the stup keys; 2 beeomes REE if Stap Is pressed. 
Seme other keys gen alsy detected; soe the keybourd decado 
taldees of abeud Ebogd far this, Only Stop ta constant between 
ie s0U2 ond other PET OCR machties, whieh is why Les 
seroen serolling is slowed by Reverse in noa-s032 machines, 
and by the back arrow tn the #032, 

fncrenent the correetion cioek, If [t Im #026F, rexaet to zere 
and skip the jiffy clock inerenent. 

Inerement the fily clock. Thin in in SKD-S$HP (50200 $0202 Ia 
BASIC 1) wlth the Mont mignillennt byte Prat, 
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SFT45 


$F7SC 
SFT62 


$F76D 


$FT70 


SF7BC 


$F80s 


$FG12 


$ra2a 


$Fa35 


$YaT4 


$F784 Compare the jiffy clock’s value with the constant held in the 
table below, If identical, reset the jiffy clock to zero by 
putting @ into each byte. 

Reset correction clock to zero. 

Get keyboard PIA value {with debounce) and store it: i.e. 
fetches contents of $E812 and puts result in $98 or $0209. 
Table of three bytes. they are HF. #1A,#01, This {ts the 
constant for 24 hours. 79*2567 + 26*256 + 1 = 5 184 001, 
which is 24 hours of 1/60th scc + 1] extra 60th second. 


$F798 
SF7AL 


$F7AC 


SFTAF Set Input device. $FFC6 of the ‘kernei' jump table comes here. 
On entry, the X register holds the logical file number of an 
open file. This makes an [EEE device a Talker. See the 
description under FFC6 in the table of common kernel routines 
for details. BASIC 4 is slightly different from BASIC<4, since 
it clears DS$ in addition to ST. The DOS wedge program’s 
source listings refer to this routine as ‘Check out’; three 
errors can occur, causing 7FILE NOT OPEN, ?NOT [INPUT 
FILE, or °DEVICE NOT PRESENT error messages to appear. 


Set Output device. SFFC9 of the ‘kernel’ jump table comes 
here. On entry, X holds a logical file number. The IEEL 
device corresponding to this file becumes a Listener, provided 
no error is detected. This routine, like the previous one. can 
print one of three possible errors, which are ?F({LE NOT OPEN 
*NOT OUTPUT FILE, and ?DEVICFK NOT PRESENT. See the 
description under FEC in the table of CBM kernel routines 
for more detaits. Note that this latter pair of routines, 
‘Check in' and ‘Check out', only actually influence the peri- 
pheral device when this is on the IEEE bus, i.e. with device 
number greater than 3. Tape, screen, and keyboard fites are 
merely validated, and the current input device number or 
output device number is set so that prompting messages and 
sc forth are not printed where this would be superfluous. 
The input device number is stored in SAF or $0263, and the 
output device number in $BC or $0264 (BASIC>i and BASIC 1 
respectively). 


CASSETTE TAPE OPERATING SYSTEM 
$Fa4a8 


$F7FE 


Increment tape buffer painter. This short subroutine (i) sets 
($06) to 027A or 033A. depending on the duvice number ia 
$04; (i) inerementa either $BB or $BC, again depending on 
$D4; (lili) compares the result with #CO (192), so that if 2 ia 
- get on return from the subroutine, the pointer paints to the 
end of the buffer. 


Test cassette keypress, If a casactte key is pressed when this 
routine is entered, nothing further is done; exit immediutely 
takes place. Otherwisc, PRESS PLAY ON TAPE #1 or Z is 
printed to the screen, Now a foop ia entered; this repeatedly 
teata the Stop key and tho caszette. A cassette keypresa 
prints OK and the routine is finished: the Stop key of course 
aborts the taupe read. 

Test cunsetta Keys subroutine, Tf the Z flag is pet, 4 key in 
pressed, if not.not. Sa fur example LABEL JSR FavA/ BNE Lanek 
loopa Indefinitely until o key iy proved. SEAIO is tested for 
bit 4 (tape #1) or Bit 5 (lape #2) high. 


PRESS PLAY AND RECORD.,. This Is Identical to the routine 
which tests the casactte for a keypress. following thin with 
PRESS PLAY ON TAPE ... exespt that an additlonal measeges 
AND RECORD, le interpolated before enterlng tha variler 
routine, 
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SFaGA 


$F890 


SF8Aa 
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$Faug 


$F8BC 
$F8328 


$FOIB 


$FaDc 


SFAF6 


BASIC2 BASICS 
$F89A Read Tape. On entry, (FB) and (C9) point to the low and 


$Fe55 


$F855 


SFS5E 


$F864 


$F873 


$F882 


$Faa6 


$F889 
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$F89B 


$PaA8 
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high locations in RAM into which tape duta is to be loaded. 
(F7) and (B5) are BASIC I's equivalents. This subroutine 
can be used to read any blocks from a CBM tape. 

Sets ST=0, sets load/verify flag to load, rand sets (FB) and 
(C9) according to device number 1 or 2 in $D4 or $F1 with 
BASIC 1, to 027A-0334 or 0334-O03FA. So exactly one block 
will be read into ane or other cassette buffer, This routine 
loads a header for FSAE/F5A6/FSE5; the block can be identif- 
ied ag a header by its first byte, #1, #4, or #5. 

This routine skips the call which sets (FB) and (C9) to point 
to a cassette buffer. It loads data direct into KAM from tape. 
it does not read blocks of data, but consecutive bytes written 
one after another. If there is a checksum or other error the 
second copy of the program on tape is likely to be able to 
correct the load; the probability of an unrecoverable error 
increases with program length. 


Initialise for tape read. The interrupt is masked and these 


locations zeroised: 
$C0,$C1,§C2,$5CB,$CE and $B2 


With cassette #1, CA1, and with cassette #2, CA2 is enabled. 


X is loaded with #0EF and the tape read/write routine FD1IB/ 
F89R/F8E0 entered. #E corresponds to the fourth interrupt 
vector from the table of tape interrupts. 


Write Tape. This first entry point is used to write data files to 
tape; it sets addresses (FE) and (C9) from the cassette device 
number, then: 

Set inter-block time counter, $C3, to 20 decimal, then: 

Write consecutive bytes from RAM to tape. This entry~point 
is used to write headers; however, a larger value, 105 decimal, 
in the counter $C3 ensures 4 longer delay than obtains with a 
block of data. Timer #2 in the VIA is interrupt-enabled; this 
ia used to control the timing of writing onto tape. X is loaded 
with #8 (correspending to the first interrupt vector from the 
table of tape interrupts) and the following is performed: 


Tape read/write subroutine. This is shared by both of the 
other routines on mis page, It sets a new [RQ; with Read, 
the vector is F9SF/FO3L/F9T6 (when offset X=#0E}, and with 
Write FOCE/FCS4/EC99 (when X=-#08). This interrupt will be 
made active when the interrupt mask is cleared with CLI. 
$E9t3 is decremented; this, like POKE 59411, disables the 
normal retrace inlerrupt; only the carsette interrupts are now 
enabled, Also, several counters and flags are Initiniised, 
Now the cassette moter is awitehed on. This involves setting 1 
bit low; the procesa Is the reverse of FFED/FCAG/FCEB, which 
turns beth motors off. : 

1/3 rd second delay for motor to plek up speed. (Omitted In 
BASIC 1, whieh helps explain Ita greater unrelinbility), 

Seth Umer #2, churns the fnterrupt disatle musk, and waits for 
the IRQ veutor to be reset lo normal. (0 Gexts the Stop key 
gad also updates {he clock when the retrace Intverupe Mag is 
high, su the clock (and the Stop key fest) are both updated 
In the normal way. The processing js done during the Inter~ 
rupts, at the addresses Ilsted above; sco locations murked *. 


. 
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BASIC! 
$F919 


$FOLE 


SFO2E 


SFOSF 


SFAA3 
$FACS 


SFBLL 
$PB23 


$FBSB 
SFBDC 


SEBES 
SFBEC 


SFCUO 


$FC21 


$FCCF 


SPCEB 


g¥FED 
$FDIC 


$FDs0 
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$FSEG6 


SFBFO 


$F900 


$F931 


SFAS7 
$FATE 


SFABB 
SEACF 


SFB2B 


SFB7G 
SFBTF 
SFRBS4 


$FAI3 


$FBBY 


$FCS4a 


SFC?7B 


SECAB 
SFCHA 


SFCCO 


$F92B 


$FO35 


SF945 


$FS76 


SFASC 
SFABB 


$FBOO 
$PBt2 


SFB7G 


SFBBB 
$FBC4 
$FLCS 


$FBDS 


SFBF9 


$FC99 


sFeca 


$FCER 
$FCK9 


$FDOB 


~438- 15: CBM BASIC ROMs 


Await [RQ's return to normal; test Stop key and action it if 
it's pressed. This tests Stop with the usual routine, but mod- 


ified because the tape and interrupt vectar need to be aborted. 


In addition the [RQ vector is exumimed - in fact its high byte 
only, which is enough ~ and the ‘equals zero’ flag is set true 
when this happens. : 


Set VIA timer #1 to new value, synchronized with timer #2 
becoming zero. Timer #1 is set to a niuitiple of the contents of 
$CB Or SET with BASIC 1, and the entry value of X. The 
timing is uesd by the tape read routine. 


Read bits from tape: interrupt entry when table offset = #S0E. 
After a timed delay, this routine sets timer 22 to a 65 miti- 
second cycle and and reads the tape. $DF builcs up a byte 
by rotating each bit in consecutively. When 8 bits have been 
input, the ‘byte received’ flag in $R2 is set, and the byte 
stored in RAM. 

Store bytes in RAM, This stores characters from (FB) up to 
(C9). It also performs the tape error checking : 

Flag ‘Long Block’ error into ST, setting bit 2 of ST (+8 dec.). 
Flag ‘Short Block' error into ST, setting bit 3 of ST (=4 dee.). 
Comparison and error-storing routine, which puts errors into 
the low end of the stack ($0100 Ff.) and compares, where 
necessary, on the second read. 

Flag ‘Unrecoverable Read Error' into ST, setting bit 4 of ST 
(=16 decimal}, 


Puts (FH) into (C7) - header pointer back to start of buffer- 
Flag contents of A into ST byte. 

Reset flags for new byte. Sets various flags to §, and the 
bit counter $87 - 026C in BASIC 1 - to #4. 

Write a tone to tape. Timer #2 is loaded with a value, and 
the cassette output bit is reversed by EOR. This is usud to 
write a bit to tape, The timer is inaded with #0060, #0014, 
and (next routine) #0110, giving different Frequencies. 
Within this routine, the timer's valuc depends on the contents 
of SDD ($FC in BASIC 1). if this ts even, #60 is loacted: if 
it is odd, #80. 


Write bits to tape: interrupt entry when tuble offset = #504. 
This uses the previous routine to write a tone onlo tape. The 
actual frequencies used for bits Band 1, and details of the 
pnrity bit and inter-byte marker, are quoted in ‘The PET 
Reveuled' on pp. 136-7. 


Write a dock to tape. This is called from ‘Write header’. It 
starts by londing the timer with #$74% and writing the corre: 
sponding frequency to tape, [t resets the flags and delays, 
for a longth of time corresponding to the counter In $C3, 
which iy decremonted with every Interrupt. Finwily, the [RQ 
vector Is replaced by that corresponding to an offset af «0A 
from the table of [HQ vectors, at FCZI/FUBA/PRFO. When the 
interrupt disable Qag is set te ®, thin routine performy wriint 
during interrupts; mounwhile, §0b counta the blocks remain: 
ing to be written, 


Turn wf motors tura off abnormal interrupts / posture ERQ- 
VIA inlurcupt enables are retuened ta normal, ia. produced 
by the cutrace Interrupt, 

Turn off motors, (in BASIC } thls runs Into the NMP yeetor? 
Perform cheek sun and inerement pulnter. Checksum in EGU of 
all bytes and iw stars dy $02 (C8879 in HASIC Lo. 

Check whethor low addreys bas buen incremented aa far on Ue 
high addreva, if 40, tha ‘equals sero’ Mag, 2. de at true. 


j 
$FO38 
id 
i 
| 
{ 
: 
i $FD3F 
; SFD9OH 
i 
{ 
; 
i 
j 
$ED249 


—- 
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$FCDI 


$FCD8 
$FCF3 


SFCFB 
SFCFE 
$FDO1 


$¥bil 


SFU 
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SFDI6 


$FDIE 
SFDIE 


SFD43 


4FD49 
sFD4cC 
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Power-on Reset. (FFFC) in the 6502's hardware vectors points 
to this addrese; this is the first software activity which occurs 
on switching on the macine. I[t may also be called during the 
course of a program; for example, SYS 64824/64721/64790 from 
BASIC clears RAM and resets alf major pointers (it does. how- 
ever, also leave the cassettc buffers and some other RAM 
untouched}. There is anoptional branch when this routine is 
enlled; if bit 7 of $E810 is high (this line is called the 'dia- 
gnostic sense line’ because of its behaviour in BASIC 1}, the 
monitor is calfed rather than BASIC. This is the reasoning 
behind one of the reset switches of Jim Butterficld, which 
relies on simultaneously holding $£810 high and pulling the 
reset line to the 6502 low. (n this way, BASIC is preserved, 
BASIC 1 does not have the monitor; the branch executes a 
diagnostic routine, which wus dropped from later BASICs, It 
required some wiring to the ports (see e.g. ‘The PET Reveal- 
ed' for an account of this. Note that the keyboard connector 
too has to be disconnected from the main board and wired up). 


The following operations are performed: 

(i) Set the stack pointer to #FF (i.e. top of the stack): clear 

the decimal! flag, which may be set; set the interrupt disable 

flag, in BASIC 4 - a precaution which the other ROMs don't 
take; set the 1/0 registers, calling EIEZL/E1D1/E000 - and, in 
the 8032, tinkling the bell; this also sets the IRQ vector. : 

(ii) Point NMI to -/C399/B3FF, where it will simply print 
READY. (BASIC I has no NMI vector in RAM). 

Point the BRK interrupt to the B* entry point of the 
moniter. {Net in BASIC 1). 

Pcint USRCMD of the monitor to print ? when an unrec- 
ognised monitor command is entered. 

(iii) Clear the interrupt flag and jump to initialise BASIC or 
exceptionally to C* in the monitor, if the dingnostic sense 
line is high. 

Set vectors except ARK. 

Test PIA for diagnostic sense, 

Diagnostic routines of BASIC 1. These are activated in a wired 

up PET on switchon. Like the tape routine they use interrupt 

vectors rather freely; the table of interrupts in BAS(C>1 has 
gops Jeft over in it apparcnily becuuse of this. Oddly, if an 

error is detected, the routine goeg into an infinite loop; there 
are many of these in ROM. Some memory routines are usable 
without hardware; for example,* the entire contents of FODD- 

FUFA (64989-65018) may be moved to RAM, with un RUS poked 

at the end; this routine will perform a checksum on ROM from 

COO0-E7FF and FOUO-FFF?, the result of which ahould be zero, 

held in $0279 (643 decimal). 

In BASIC 2, Moniter entry is FD11, BASIC Initialisation E116. 

In BASIC 4, Monitor entry is DATZ, BASIC initialisation DIEB6, 

NMf vector. BASIC?! performa indirect jump to (094). 


Table of IRQ vectors for tape handling routines (and diagnos- 
lies in BASIC 1), 


Machina-linguage montlos. In BASIC 4 this kas been gaved 
le D472, so bE have put ity ROM detalls there, following tho 
sequence of BASIC4 miter than BASIC Z, 
Millenia! copyright statement: C 0078 CBM. 
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The 'Kernel': Disk routines only. 


$FF93 CONCAT. Jump address: DAC7 
$FF96 DOPEN D942 
$FF95 DCLOSE DA07 
$FF9C RECORD D7AF 
$FF9F HEADER DSO2 
$FFA2 COLLECT DAGS 
SFFAS BACKUP DATE 
SFFA8 COPY DAA? 
$FFAB APPEND B97? 
$FFAE OSAVE DBO 
$FFB1 DLOAD DB3A 
$FFBY CATALOG or DIRECTORY 0473 
$FFB7) RENAME DB55 
$FFAA SCRATCH DB6s 
SFFBD GET DS$ (DISK STATUS) D995 


$FFCO to $FFEA -~-- Kernel jump table: see next page. 


$F52A $F521 $F560 SFFCO (OPEN) - jump address. 

$F2CB $F2A9 $F2DD SFFC3 (CLOSE) - jump address. 

SF78B $FI70 $F7AF SFFC6 (Set input device) - jump address. 

SF7DC SFISC $F7FE SFFC9 (Set output device) - jump address. 

$F27D $F272 $FZAG SFFCC (Restore default 1/0} - jump address. 

$FIDE $FIE1 $F215 SFFCF (Input a byte} ~ jump address. 

$F230 $F232 $F266 SFFD2 (Output a byte} - jump address. 

$6396 $F3IC2 $FAOt SFFDS (LOAD) - jump address, 

$F69E $FESE $F60D SFFO8 {SAVE) - jump address. 

$F498B SF4B7 $F4Fe SFFOG (VERIFY) - jump address. 

$F695 $F68% $F6C3 $FFDE (SYS) - jump address. 

$F339 $F30F $F343 S$FFE1 (Test Stop key) - jump address. 

$FICC $F1DI $F205 $FFEu (Get 1 character) - jump address. 

SF2A% $F26E $F2A2 SFFE? (Abort ali 1/0) - jump address. 

$F736 $6729 $F758 $FFEA (Update clock/ store key} - jump address. 

$FFED Turn cassette motor(s) off, This subroutine ends with RTS, 
#$60 In hexadecimal, which 'mangles' the low byte of the NMI 
vector. 4 

w-7- ($FFFA) ---- NMI vector: 
BASIC 1; 5CA60 centers a routine to print a character. 


BASIC 2: SFCFE 
BASIC 4; $FD49 


Reset vector: 

BASIC 1: $FO38 
BASIC 2: $FCD1 
BASIC 4; SFD16 


IRQ vector: 

BASIC 1: 5SEG6B 
BASIC 2: SE61B 
BASIC 4: SE4&%2 


---- ($FFFC) ---- 


---- ($FFFE) ---- 
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FFCO 
FFC3 
FFC6 


FFCS 


FFcc 


FFCF 


FFD2 


FFDS 
FFDS 
FFOB 
FFOE 
FFE1 


FFEY 


FFE? 


FFEA 
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The ‘Kernel': Routines common to ali CBM BASICs. 


nn ae 


OPEN Identical to BASIC OPEN. 
CLOSE Identical to BASIC CLOSE. 


SET INPUT DEVICE LDX Mogical file number/ JSR 5FFC6 prepares the 
logical file number in X for input. The routine preserves A,X, and ¥Y; file 
details of device and secondary address are taken from the tables. In the 
ease of IEEE devices, "TALK' is sent. This routine also checks that the file 
is ready: if the file isn't open, ?file not open error results; if the file is 
open to tape with non-zero secondary address, ?not input file results; and 
if the high bit of ST is set, ?’device not present error results, (Other IEEE 
errors may be reflected in ST and DS). 


SET OUTPUT DEVICE LDX #ogical fite number/ JSR SFFC9 prepares the 
ogical file number in X for output. The routine preserves A,X, and Y; 

file details of device and secondary address are tuken from the tables. in 
the case of IEEE devices, 'LISTEN' is sent. This routine also checks that 
the file is ready: if the file hasn't been opened, ?file not open error will 
appear: if the file is open to the keyboard or to a cassette file with zero 
secondary address, ?not output file results; and if the high bit of ST is 
get, ?device not present error results. (Other IEEE errors may be refected 
in ST and DS}. 


RESTORE DEFAULT f[/O Makes the output device 3 (i.e. screen) and the 
input device 0 (i.e. keyboard). The locations involved are $B0 and SAF 
respectively ($0264 &£ $0263 in BASIC 1). In addition, an output device on 
the [EEE is unlistened, end an input device sent the untalk command. 
None of these files are closed by the routine, Note that X and Y registers 
are preserved. (BASIC<4 has a bug: sce Chapter 14 on the (EEE bus). 


INPUT ONE CHARACTER This routine is a subset of INPUT and INPUT#, 
which takes in a single character and - in the case of screen input - prints 
a flashing cursor and advances the cursor an input. (Some monitor source 
code calls it 'RDT'). [t sets ST to zero, then, according to the input device 
number (SAF or $0263) separates into keyboard/ cassettes/ screen/ or [EEE 
routines, {n each case on return A holds the input character. Note that the 
contents of X and Y are unchanged. (f ST<>U, [EEE devices return #0D. 
OUTPUT ONE CHARACTER This routine is culled by PRINT and PRINTE; 
it outputs the enntents of A to any device. {n the case of the screen, the 
character is treated as CBM ‘ASCII’, so e.g. LDA #$93/ JSR $FFD2 clears 
the screen, If the output device is 3. The output device (location $B¢ or 
$0264) determines whether cassette, screen, or [EEE output odtaina, The 
contents of A,X. and Y are preserved. 


LOAD Identical to BASIC LOAD, 
SAVE Identical to BASIC SAVE. 
VERIFY Identical to HASIC VERIFY. 
SYS [dentical to BASIC SYS. 


TEST STOP KEY JS{t SEFEI (that's all!) within machine code tests the 
key-image stored by tie clock update routine to see whether STOP wns 
presen. Mf so, They are averted Cefluctively by FFCC} nnd READY Appears. 
if SUG (S029 tu HASEC 1) fa foreed to ake, this will no longer work. 


GET ONE CHARACTER Alinost identien! to EFCF except that keyboard input 
ja tuken from the keyhoud buffer. Se thal, for example, the equivalent of 
GEL X$; fF AS“ GOTO 10 ia JSR SEVE4/ WEQ-5. X and ¥ ere relilied, 
ABORT ALL I/O) Sets the namber of flew oped lo sero, then in effeet colts 
PECK The Giles are got cloned, CLR and abmilae renstines call this. 

UPDATE CLOCK AND STORL KLYPE!SS inerementy the jiffy clark Guiness 
the correction clock resety) gid eaves the keypress which FRET uses, 


P . 
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CHAPTER 16: MATHEMATICAL PROGRAMMING 





16.1 Computation 


Accuracy What do these three expressions have in common? 
,55 + 132 = .87 
3/5 * 5 £3 
Ol1+ .05 = .06 


The answer - which xppties to those machines (PET. Apple. etc.) using Microsoft 
BASIC of single-precision accuracy - is that they are all false. At first sight this is a 
disturbing fact, but all computers with digilal storage have this problem, so there is 
no need to be over-concerned, When I say that all computers have this problem, I mean 
that the difficulty is inherent in these machines. A number Like 1/3, for example, 
which is expressible as an exact fraction, can't be stored as an expansion in decimal 
ov binary farm without losing accuracy. Large machines, or those with 16-bit chips or 
more precision in the way they store numbers, are less pronc to problems of this sort 
than smali ones, but the basic difficulty remains. Chips which perform only cuiculation, 
as uscd In the DAI for example, have internal registers which indicate when a result 
has been rounded, and also the lower and upper limits of the result. To ensure that 
no problems are met with in programming the CBM, we nead to examine the number 
storage system, Leaving aside integers, with which no loss of precision is possible, 
floating-point values are stored in RAM as 5 bytes. Chapter 4 shuws how numbers 

are stored poth as variables and in the flouting-point accumulator. The securacy is 
greater in the accumulators than in varinole form, because un extra byte is used to 
retain values which are later rounded when the result is stored further up in RAM as 
a variable's value. Such values are stored like this: 


— < ESEN-e a a 
BYTE 1 |. Seer a BYTE 3 BYTE 4 


EXPONENT SIGN “BIT AND MANTISSA 21 MANTISSA 3 | MANTISSA 4 
MANTISSA 2 ' 
— ee 


This is a very stundard arrangement, in which every increase in the exponent (byte 
1) doubles the value, and where the mantissus are arranged in decreasing order of 
significance. A single bit holds the sign. To make this clear, let's consider some ex- 
amples. The non-mathematically minded may like to skip this section (and probably the 
entire chapter too), althougn 1 don’t recommend this. 

Firstly, the exponent. [f a variable, siy X, is put equal to @ number (X=1, for 
instance), the five bytea which store the number can be peeked from RAM, and we 
can attempt to decode what we see. X=} and X=6 give these reaults: 


3 130 o}oara 
4 i131 0; ao); 0 


The only difference between 3 and 6 us stored is in the exponent, A difference of 1 
doubdtes/ halves the result. The exception js a zero exponent; the value is then zero. 


























Secondly, the sign dit. Two ather specimen values give these results: 
-1.8 | 129/192 o[o ° 
1.5 12a} 64 |) & | o {9 
The sign change ls signalted ny the high bit of Mantlasa 1. This af course corresponds 


with the minus flag on the 6602, which mukes for eaaler programming. There ia no 
point In taking up more spuce than t bit, since a sign has onty two alternative values. 






Thirdly, the mantinsas, Because the highest bil is used fur the sign, ¢he num- 
bor's value [stored [nd bytoa town 1 bit, making 31 bits in all. The signifleance of 
these bitw la hard to oxplain: they span a ennge fren 1 to 1.999999... which, when 
mullptled by an exponent, itself of furm 29, Gikea in the ontire range from about 
10798 to $098 with accurucy of } pure tn 1018. Tha following formula will convert any 
numeral) stored in this way, iInio ita musacric uquivalont: 

(-1) (al AND 128) © 2 TCEXP~120) * (1 © (imi AND LAF) o CMDs (M92K4 290) £395) 7228) £224) 


. 
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The following examples may make the meaning of this forniuia less obscure. They cover 
a fimited range, from 3 to 8:- 


16: Mathematical programming 


a 





er aan 


Numbers between 4 and 7.9999... have the same exponent, 131, The sets of Figures 
here recur for the whole range of exponents, giving 8, 10,12,14 next, 2,23.3,34 pre- 
viously, and so on. The exponent, minus 129, and raised to the power 2, multiplied 
by the mantissa, gives the result, and we can see from the examples of 4 and & that 
a constant } is added to the mantissas, The following bits are weighted, so that div- 
ision of the bytes by 128,256,256, and 256 successively scales down the final bit to an 
appropriately tiny value, and assigns the greatest weight to the earliest bits. The 
examples are translated like this: 


32241 wultiplied by 1 4 64/128 «© 2614 =3 
au 242 hid £+0 = 4*1 34 
S222 ‘ 1+ 92/128 = 4*1 1/4 <5 
S=22 * 1 + 64/128 = 4"1d =6 
Te 2t2 " 1+ 96/128 = 4*1 3/4 =7 
8= 23 Ls 3+0 = &*t 8 


To decode a number, using a povket calculator (or a PET!) the easiest method is to 
start at the lowest byte, divide by 256, add the next, divide by 256, add the next, 
divide by 256, and finally add mantissa 1, iess 128 if it excceds 127, divide by 128 
and add 1, The result. between 1 and 1.99999... imust then be scaled up or down 
according to the exponent, and assigned positive or negative sign. This is what the 
formual on the previous page does. Here are some further examples, with their correct 
values at the foot of the page, for those who want ¢o test their grasp of the idea: 






155| 62(iaa | 31/224 
Converscly, Ict's see how ta express a real number in floating-point form. Let's take 
-13.2681 as an example. The minus sign means we must set the high bit of mantissa L. 
@ ig the nearest power of 2 to 13.2681, as 2:8, So the exponent is 129+3=132. 
13.2681 = 8 * (1°5.2681/8) = 8 * (1+ .6595125). The value following 1 is the number 
which Ja to be approximated by the mantissa: 

6595125 * 128 = 84.2896, 


.2896 * 256 = 74.1376, 
11976 * 256 + 35.2256, and 
.22568 * 256 = 57.7936. 


Therefore, the nenrest approximation fs: 


[ise| stare [aus] 


Section 16.9 gives muchine-code reulines to perform these conversions; thia Is usefut 
when finding the values stored in ROM tables and in RAM, We can put this knowledge 
to work in ayolding rounding errors, Since J1 bits atore ihe vaiue of any number, 4 
nuperat which does aut overrun the final bit will be held exactly, Integers up Lo about 
22 are held without loys of uccuracy, The extreme value may be found by tests liku 
PRINT 2 £50 009 O00 = 2 180 900 NOl1.UNtil the anawer in -1, menning ‘true’, for a large 
enough puaber, at whieh point the smallest blt na longer disthaguishes the very last 
figure, Caleulatiann oo exaet Integers Cle. frum avout 2 Slain 2 Flare, su fur aa t 
Know, arcurste, when addition, aubtraction, multiplication and dlviaion ate iivelved, 
wlithough obviewsly functions auch as SiN or LOG will involve rounding error. Thia Is 
the renson thet toopy with integral values execute correctly. FOR Jat TO 10G0U0: NEAT 
tgecutes correctly up lo the lavt value, whieh da stored sa though J: 100000 had just 
been entered, Dechuale are teas Immadiately obvious, Thera wil be errors If the frac- 
tlon 1a not some combination of J, 1/4, 1/4, 1416,..., 2°91. 4 loup with Kieg-aize 1.3, 
or 2.75, or 7.325, or .00990625, will execute correctly; but 4,4 or 9.26 or be.e? will 








= 


Decimal vatues are .1234, 144.75, and 9OU0UOUM reapectively, — 
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not, since these are stored as repeating numbers in the binery system, like 1/3 in the 
decimal system. There is also a problem of the relative magnitude of the numbers con~ 
cerned. .60390625 (=1/256) is stared exactly; but if it is added to @ huge integer, 
which also is stored exactly, some precision is lost because of the differenc: between 
exponents of the two numbers. Some of the smaller number's bits will be lost; in effect 
it will be truncated. 

As an exemple of the application of this knowledge, the program which follows, 
and a specimen run, divides two decimat numbers. printing the result with no loss of 
accuracy. The program run divides 123 by 19, printing 75 decimal places of the result. 
Its BASIC looks more complex than is reatly the case: line 20 checks the input values 
of numerator and denominator; lines 30 and 50 are complicated by the need to delete 
spaces before numbers, 4 (requent irritant with PET SASIC. Line 30 prints the number 
preceding the decimal puint; line 40 updates the numerator, removing the equivalent of 
the part just printed by line 20 or 50; and fine 50 prints a single digit. The lines with 
N stop the loop after N decimal places. The point is that no error is introduced by the 
calculations in 30 - 50. 


NOEFINITE PRECISION OIVIS{LON: 


10 INPUT “Xe ¥sN°S Xe Yon ; . 
90 1F X > 21E8 OR Y > Z71E8 OR ¥ ¢) INT(Y) OR XQVINTOCX) THEN FRINT “ERROR”: 


30 PRINT LNTEX/¥)# “CLEFTI. “3 


40 X = OX - INTOX/Y¥}#Y) # 10 
$0 PRINT MIDS(STRSCINT(X/Y) +208 
60 N = N-1L 
70 IF NL THEN 40° 
EADY. 

EXAMPLE 

Xe VeN? 129 
77:19 
7? 75 


6. 473£8421052631578947 368421052631578947 368421052631578947360471052631 


This decimal repeats every 18 digits (=19 - 1}. This is a consequence of the fact that 
19 is a prime number. The sequence of digits repeatsindefinitely, and this process is 

similar to that by which pseudo-random numbers are generated. in which each number 
{g derived from the previous, and the sequence repeats, but its cycle is large enough 

for the numbers to be considered 'random'. As a more ambitious example, this decimal 
repeats every 330 digits (45678 = 273*23*331). 


Xe¥eN? 12345 
7? 45478 
49 75 
Gs 270261994982257 1745698147 90489951 IFHF 22895047 94430 $7 927 2297 3GL0501 773 


If a calculation can be subdivided in this way, there ia no risk of rounding error. But 
Numbers may simply be too great to be susceptible to this approach. Multiplication is a 
good exampie; sce DBL (Chapter 5) on thia, Section 16.9 hns a machine-cade multiplic~ 
ation progrum accurate to 250 figures. Not many accountants belleve their Cures to 
be accurate to a few parts In ten billion, and it Ia often unnecessary to bother with 
large-figure accuracy. Smail figurea, paradoxically, may give teauble. [ can rememuer 
a demonstration of an incompleta rccords accounting system which, ut the urd of a tong 
perlod of Input of figures, announced that the tatals didn't baluned, The balaneing 
amount wap roveaied to be zero. Obviously the figure waa held ag .0UN00001 ar nome 
thing sinlar, and a test for 'eruality’ wee used whieh required ait the bits to be 
Identieal. The result should have buon rounded ty the nenragt penny! cent, Some 
computers (e.g. DEC) have an ‘approximute equality’ func tun, definuile by the uger 
no that two values are conkiiared to be aqual if they are within a cerbcla sniall value 
of cach other, The PET equivalent is ABS (X-¥) © .0001, or whichever vive is 
selected, Accuracy bax to be considered in any serioud Bystem Involving numbers, Nav 
ROM fanues of WASIC promlae to nave more prociae srlthmetic avallubia, usbeg the 6502 
type chip's decknal mode; details of this are not evailable, but presumably deelsions 
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wil have to be made on which variables should use this mode, and perhaps how mary 
bytes ought to be allocated. In the case of current CBM it may be worth performing 
arithmetic in integers only (i.e. floating-point numbers having integer values). Some 
calculations yielding non-exact values, far example percent markups, will have to be 
rounded at each stage. A trial program wilt show whether this is necessary. With luck 
it won't be. Some calculations though, which are within CBM equipment's capacity, can 
come past the point where small cumulative errors show: stocktaking (‘inventory' in the 
U.S.) may show smatl errors between totals end subtotals. 

{n mathematical work, the rule should be to prefer methods which yield a result 
with the smallest relative error, where there is a choice, Three examples. involving 
the statistical concept of standard deviations, the solution of quadratic equations, and 
series summations should illustrate this idea adequately: 

(i) Standard deviation, This statistical concept is related to the normal distriv- 
ution and to the idea of the average or 'mean', It is a measure of variation, equal to 
the average of the sum of squares of deviations of exch item from the joint mean. Let's 
take a simple example: two numbers only have been taken, the result of some measure- 
ment, and these are 1000 and 1001: We assume they are completely accurate. Their 
mean is 1000.5, which we can assume ig the mean of their total distribution: ali we are 
interested in here are computational problems. The deviations from the mean are -.5 
and .5; the squures of the deviations are .25 and .25; so the average of these devia- 
tions is 3(.25 + .25) = .25. There is obviously no error in this result ascribable to 
the computing technique used. However, by standard algebra, we can prove this 
general result: Zia) 

a 
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o.d.t = 46 Za-x)? © 


which implies that }(1000? + 10017) - 1000.5? can be used in routine calculations to 
evaluate the standard deviation. The equations are algebraically unimpeachable; bul 
the calculation which results falls into the trap of producing a result by subtracting 
ome number from a very similar number; in this case, each number js large, and it is 
easy to aee thet rounding errors might cast doubt on the result: 

g.d.7= 1001000.5 - 1001000.25 = .25 .- this tlae 

{ii) Quadratic equations. These are a common, rather boring, source of demon~ 
stration programs. Leaving aside the questions of imaginary solutiona and repeated 
solutions, the general solution af ax? + bx +e = 0 is: 
xb ty {b® = 4ac) 

2a 
From the viewpoint of rounding errors, it is best to use the form with the negative 
square root, because otherwise, if a or ¢ Is a smait value, the absolute vaiues of the 
two expressions in the numerator will be close, and a large relative error will result 
after subtraction. The other solution enn be found using the fact that, in 

xis px +g =o, 

both solutions add to p. 


(ii) Series summations. The short BASIC progres: Sans well-known serlea, 
10 INPUT “VALUE; ¥ BIN(¥) wv - yy? + VO we VP ove - .,, 


20 Nal: TaV:REM TeTERM ay OS, ee 
30 PARTIAL RESULTPA+T This serles converges for any value of V. since the 
40 Tos - THY4V/(Ne1L) / (NZ) ratio between numer ators increases with V? each time, 
$0 PRINT SIN(V), PA wheress the denominators' ratio increases with every term 
60 R= Ne2: GOTO 30 without converging. If each term of the series ia held 
hy a computer with cumplote accuracy, SINC 1006) will 

be evahasted as uccurntely as,though more slowly than, SIN(.1). When this ia not the 
crse, os the program shows with values of 50 or 190 say, the result will be more or 
lans awamped by Une angnitude of individual early terms. The solution ts to Cransform 
the value Into sete number which is aaaier to deat with; hare, becuse of the cyclinal 
halure of the sine curve, it ts easy to subtract on appropriate multipie of pi from the 
orignal volue, then compute the sing of the ceavlt, This la how CHM BASIC works, 
with the result that rounding errors with lLirge arguments are greatly reduced, In fact 
becoming enquivalent to the rounding errar involved ia the sulsicthery calerulisttars , 

Transfermations are caninan ino statistienL work; the stuntird deviation MWluatration 
above tends itself fam particularly easy type, since Hocan be shown that adding a 
conslant to every value inaves the standard devintlon unehanged, So tnatend of weing 
1000 ane 1001, we can enleulate the standard deviation of O and 1, 





x= 
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Solving equations: Newton's method This is one of very many methods to discover 
solutions by iteration rather than analysis. Like all such methods, it is fallible - since 
ingenious exceptional functions can be found which can't be solved. The principle it 
uses is to improve on a guess using knowledg¢ of a function (which may be pictured 
es a graph} and its gradient. Repetition of the process gives a set of approximate 
solutions: if these converge, so that consecutive trialy are equal or nearly equal, a 
solution is presumed to have been found. Generally, the user hes to supply a starting 
guess. althougn this could be done by the machine at the expense of computing time. 
Some Hewlett-Packard calculators have a 'Solve' function, where two estimates are 







asked for. The ees reiation is hy aa Gradient ot (a s4o) 
x eR 8 ae; 
nel 1 gradient at x, Sn ys = Ya / Caney -xn} 






(tas - Xp} 

The gradient is usually assumed to be the derivative, i.e. an analytically-found curve 
giving the gradient at all points; the BASIC routine below calculates the gradient, 
rather than requiring a supplied formula, so that expressions which are hard to diff- 
erentlate are still solvable. Line 10 holds the function definition, line 40 calculates the 
gradient. using an arbitrary value for dx which may be changed; line 50 adjusta the 
best estimate so far; and line 60 stops if and when the improvement in the estimate 

is nogligible. 


REM PPPPerErrTerrerrerrertrrri reli lett tit kee edd thd dlieieieielel 

REM saak NEWTON'S METHOD FOR SOLVING SMOUTH FUNCTIONS  *### 

REM ##ee LINE 10 HOLOS THE FUNCTLON +ane 

REM ##e8 CAN USE EG 10 LOG(X*N)-SIN(X),IF N 1S ALLOWED FOR sa 

RIM rerenrrrerrrerrrrrrrrr rer IIe Erte. Eats std E AD hed dllel 

| REMEMBER DESCARTES’ SIGH RULE: NO. OF CHANGES = NO, OF POSITIVE SOLUTIONS 
O DEF FN Y(X) * LOG(X) - SIN(X):; REM DEFINE FUNCTION TO BE SOLVED = 0 


‘0 INFUT “GUESS"+ GUESS + REM USER MUST SUPPLY GUESS 

oO DX # 1/1024 + REM EXACT POWER OF 2 FOR ACCURACY, 

.0 GRADIENT AT GUESS » (FN Y{(SUESS+DX) - FN ¥(GU2)/DX: REM STANDARD FORMULA 

© CUESS=GUESS - FN Y(GUESS)/GRADIENT :REM NEWTON’S FORMULA 

.O IF ABS(GUESS-G1)¢1E-7 THEN PRINT: PRINT “SOLUTION: "5 GUESS: END; REM PICK 
ECISTON 

'O PRINT GUESS! ¢t REM WATCH SUCCESSIVE APPROXIMATIONS: 

10 C1sGUESS « REM STORE THE CURRENT GUESS 1+. 

10 COTO 40 >» REM o-. AND TRY AGAIN. 


FXAMPLE RUN+ USING SQUARE ROOT OF 2 
LO DEF FN Y¥(X) = X*2-2 ) REM DEFINE FUNCTION TG BE SOLVED * 0+ 


GUESS 4 
L.4997559BR 1.4166B019 1,41421656 1.41421956 
SOLUTIOM: £1414213954 


Solving equations: Inverse interpolation Suppowe you haye an elaborate formula which 
enlculates a single value from several inputs. Such a formula typlenlly is casy to uae 
one way round, but difficult to soive the gather vary. For example, a mortgage eater: 
ation might give a monthly repayment flyure for any rate of interest: perhaps 200 ul 
5%, 220 at 1G’, 250 at 194. flow can the interest rate vurrespanding to 219 bu Tnuad? 
The obvious wny ta te cotiverxYy an the valua by yuessing wa well an possible, teatlnig 
the guosn, and kaproving on the yueod vatil a aati¢fnetory approximation is found, The 
process ts eas elegant, bat easier lo Gnidepatund, than inetueds of Newton's lLypa, 
which ds exactly the weme job. fn aur example, he interest rate Es obviously in the 
rinue 5 to 10%, we could guess THA, try this value, and amprave ft dn the light of the 
rosult, Without a caleulitor or computer, thia is tedlous, with a conpuler, it in neta 
problem, Sectlon 16.4 tig ua exampls, Invelving oa a¢lusrial cafeulation on interest 
rates, which shows tha procedure to use, 
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integration: Simpson's rule Integration is an algebraic process of aggregation, used 
to compute areas, volumes, rates of flow, strengths of fields and so on. Numerical 
integration techniques carry out the process without the need for intermediate analysis. 
Simpson's rule is representative of the type of method. It can be visualised ag a means 
ta determine the area between a curve and its x-axis. The result it produces is based 
on the supposition that the sample points which it uses are joined by a section of 2 
parabola. The cule uses an odd number of values, which we car refer to as y ,y¥,.¥.,, 

.y¥. corresponding to x-coordinates «,.%5,%,,--+5% The precision improves Rs 7 
more X-coordinates are taken, up to the Hoist dt which rounding errors caused by 
the large number of calculations accumulate. The formula for Simpson's rule is:- 

Estimate of iategral = (x step-size)/3 * Y, + 4¥, + 2¥4 + 4y, eo... # aya *¥y? 

Weights of 4 and 2 alternate, except for the end values, The BASIC program listed 
below repeats this calculation, with finer gradations in x. until estimates agree within 
a small margin. [ts example run shows that the criterion is too severe for this cuse; 
all the estimates are nearly identical, This is because the original curve is a quadratic. 
which Simpson's rule solves exactly. The program assigns a step-size. S, in line 30; 
this is repeatedly halved as the calculations proceed. The odd terms (weight 2) are 
summed separately from the cven terms (weight 4). From one step-size to the next we 
need only compute the alternate, odd, values, as the diagram shows, so that at each 
stage the even values become the total calculated so far, This cuts down processing 
time, because each value of the function is only calculated once. 








F 
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FUEL 6 Ca aa AEE ISA EAE EE EER 
REM 4 
REM * 
ROM « SO=SUM OF ORD VALUES: SE=SUM OF EVEN VALUES: S=STEP SIZE. 
* 
+ 


SIMPCON’S FULE. 
INTESRATES YOUR FUNCTION IN LINE 10, 


*£* ax 


NB: CHANGE LINE 90 IF LESS/MORE PRECISION 1S REGUIFED. 
ANOTHER VERSION OF SIMPSON; WITH GRADIENT END-CORRECTI ON; EXISTS * 


DEF FN ¥¢xX) * CPIJ « €100 - X*X)3 REM FUNCTION TO SE INTEGRATED 
INPUT “INTEGRATE BETWEEN XarX2°? XirXZ 
GS = (K2-K1L)/2: SK = FNY¢X1L) + FNYCX2) 
SE = SE +601 50 «0 
FOR J = Xt+S TO X2 STEP 2*S 
SO «© FN ¥(J) + 6G 
NEXT : 
Is(2SE 4 4950 - FN YK) - FN Y{X2) > *# 3/3 : 
IF ABS (1 -I1) ¢ LE-@ THEN PRINT “EfNTECRAL #"P Is END: REM CHOOSE 


100 PRINT f+ REM WATCH APPROXIMATIONS 

aia TT oe Ts EM STORE 

120 G5/2: IF SQ THEN FRINT "DOESN‘T CONVERGE": END 
13G¢ CATO 46 : FEM PEPEAT FOR IMPROVED VALUE 


THIS INTEGRAL CIVES THE VOIUME OF A SECTION OF A SFHERES 
EXAMPLE XUN 
INTECPATE BETWEEN X1+%2 8.7435 10 

47, 41092 

AP ALVILPF 

47 ALOFIYS 

47.415997702 

47,4109001 

INTICHAL © 47.4hu07201 
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Random numbers These are widely used in simulations of sciuntific and social phen- 
omena, where overail behaviour of a system may be modelled us the outcome of many 
indivicually unpredictable events. The concept is also widely used to explain statistical 
distributions, using, at the introductory level, coins, dice, and cards. Before the 
widespread use of computers, ‘random number tables’ had to be prepared; computer 
power enabled pseudo-random numbers to be generated as required, which was more 
efficient than storing large tables. The usual method is to derive each pseudo-random 
number by a formula from the previous number. fn this way a repeatable and testable 
series is generated. Recurrence retations are used: the number is multiplied by a 
large number, another large nuniber is added, and the result forced into the correct 
range by taking the remainder after division by yet ancther number. There is plenty 
of scope for designing series which satisfy statistical tests for randomness. Such 
series always have a period of recurrence, but tnis is enormously long. Badly thought 
aut series may have internal repetitive features of several types. Large computers 
store huge integers exactly and use these in their processing; Microsoft's random 
numbers work on similar, but not identical, lines. The differences are presumably an 
effect of the 31-bit storage methar, 

'RND! is explained in Chapter 5, and also in Chapter 15 in the ROM section. 

In view of the widespread confusion ubout this function (incidentally, it is implemented 
differently in different machines: don't assume that what follows will apply to non-CBM 
equipment) let me summarise its three main fertures: 

(i) XsRND(0) or PRINT RND(Q) are two expressions containing the function 
RND. RND behaves like all other arithmetic functions in BASIC, and can be assigned, 
printed, compared, ‘calculated with, and so on. This should be straightforward to most 
people who have experimented with BASIC. 

RND{O) is a ‘truly’ random number. * [t is generated from four timers inside the 
VIA chip, which decrement every microsecond with the clock, so that any single use of 
this function generates e number between 0 and 1 which is non-repeateble in the usual 
sense. However, because the whole computer ia controlled by a single set of timing 
pulses, repected uses of this function are often non-random, unless (for example) an 
external event like a keypress influences the timing. For example, suppose a BASIC 
program happens te loop in exactly 65milliseconds. Then RND{) is exactly the same 
on each call! This is because the timer goes through a complete cycle in 65 thousand 
¢lock eyclea. Try this with the ‘random walk’ program in Chapter 5. Note that BASIC 
l has a mistake in its ROM: evidently the VIA was moved at the last minute, and the 
addresses assumed in BASIC 1 were not updated from $9040-$904F. 

(J) RND (positive argument). The value of this function depends only on the 
stored random number, |.e. usually on the previous value returned by RND, RND{1L} 
and RND(99999) in identicai circumatencea return equal values, A series of calls gencr- 
ates numbera from zero to one in e predictable sequence, euch depending on the last. 
Their period of repetition is large. 

(iii) RND{-ve}. This function depends on the argument; {¢ ls ulwaya the same 
for a given argument, Thus, PRINT RND(-2);RND{-2);RND(-2) prints three identical 
numbers. The point of thls ia to enable programa containing RND to be tested: if 
RND{-1) say is entered at the start, rather than KND(O), all the subsequent RND(rve) 
valuey will repeat when the program is ro-run, This is helpful during debugging. 

RND (+ve) works by multiplying by 11879546.4, adding 3.92767778 x 1078) 
interchanging two patra of muntissas, setting the exponent to 128 feo tha maximum 
value is .9999...), and normalising the result. RND(-ve) skips the two calculations, bul 
ja otherwise Identleal. These examples show how RND(-ve) appears in $48-8C, where 
RND |s stored. (BASIC 1 uses $2A-DE). Note the small values produced by Integers, 
a result of the Interchange process: ; 
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The RAM workspace in which random numbers are stored is immediately after the 
CETCHR routine: on switchon or reset, both are together copied from ROM into RAM, 
so that there is a constant ‘seed’ value* when the machine is switched on. Section 16.3 
inctudes examples of random numbers used in simulations. 


Permutations and combinations This statistical topic ~ sometimes called ‘combinatarics' + 
uses the so-called ‘frequency theory of probability’ to construct theoretical modets of 
actuel distributions. For example, the possible of combinations of two dice throws can 
be listed by hand (1,1:1,2;1,35 «+. 36,6); there are 36 of them. If we postulate that 
each combination is equally likely to occur, we can construct a model of the distribu- 
tion, which can be generslised into the binomial, Poisson and normal distributions. The 
details are too complex to summarise here. From the point of view of computation, it is 
worth knowing that factorisla can be rapidly estimated: . 

A factorial’ (21=2*1=2; 31=3*2¢1=6; 4'=443€2*1212; ...) is @ rapidiy-increasig 
function which turns up in many combinatorial calculations, since n! is the number of 
ways in which n different objects may be put into n pigeanholes. It is in fact a spemal 
function called the 'gamma function’, but with integer arguments only. Stirling's form~ 
ula approximates factorials; 


i n 1 1 139, 7 
nt=(n/a) a/C2en) [1 + 335 * gagnZ ~ 51e4on? * 348692004 zed 


Rather than use this series directly, we can find togein!) which gives results usable 
up toe n-10736 without overfiow. The expression in square brackets can be approxim- 
ated by exp (i/12n) without much loss of accuracy. giving 
1 
log,{n?)3 2 logan -n + diogg(2nn)+ Tan 
= (neh) Clogen - 1) + 1.4189 + Kk 

This short BASIC routine calculates the value of pCq. the number of ways in which 
q objects may be selected from p: 

10 DEF FN LF(X) = (X+.5)*(LOG(X)-1) + 1.4189 + 1/(129%) 


20 INPUT P,Q 
30 PRINT EXP(FN LPP) - FN LF (Q) - PN LF (P-Q)): REM Pt/(Q!(P-Q)!) 


40 GOTO 20 


The norma! distribution This well-known distribution, discovered by Gauss, !s usualty’ 
represented as a beil-shaped curve with two parameters, the mean and the standard 
deviation (m and s, say) with equation 

(- (xm)? /287) 

eVtxy 


When the mean is zero and standard deviation one, the expression simplifics to 


n(a) = exp 


nix) » exp (-3x*) 
STIR 
This distribution applies to measures theight, weight, tength, etc.) in which the final 
result is influenced by a large number of individually small influences, [t la not a very 
easy function to deal with; sometimes approximations are casicr, such as this sugges- 
thon, where -34=x<¢=¢3: 


a 
n(x) # 45% awe 


Normal distributiona can be simulated in a number of ways. The BASIC rouline which 
follows uses ub algorithm by Knuth’to genernte 4 gerfes of ‘random’ values with ppec- 
fled mean and standard deviation, The example simulates [Qa Ae measured by one 
type of pancil-and paper lest (ethorsa have different standard deviations, so that their 


resull# vary more). 


The need in tect canant be menumed to be ‘oxactly conatent, Thece iu A pragramming 
uleteke Ly tha exapreagion which moved GETCHA and the aged vatue; the loop Ja one byte 
tow ahort, #0 tho ftnal byte of the seod in ant actually tranaferted, So tha sord’as 
ealue dapends on the conienta of $AC ($DE in BASIC 1). The poasible range of values ts 
about .4)1639137 to .8i365196. 


PNote that Of (nol defined by the muliplicative caries) ia 1. 
Shonald M. Rnuth, ‘Tra Act of Computer Programming’. 7 volumes. 
. 
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KNUTH'S ALGORITHM FOR NORMAL DEVIATIONS 


5 SIOMATLS: MEAN =100 

10 Vi = 2#RNDG1)-1 

20 WO =# DeEND(1)-1 

30 S$ = V1L42 + V2"2 

40 LF S)2 1 THEN 10 

49 REM DEVIATE 1S: SIGMA # V1 # SQRi-2#LOC(S) /5)- 
SO DEV:ATES S{GMA # V1 * 7QR¢-2*LOG(S) 4S) + MEAN 

§5 PRINT DEVIATE 

60 Y1=V2; GOTU 20 ‘ 
READY. 


104, 6919997 
85. 4869251 
117,30 1967 
75. 6151702 
Fa, O19 2871 
81.40724698 
61, §407044 
100. 406391 
83. 4850424 


Probability distributions The binomio! distribution models the occurrence of independ- 
ent events, giving the probability of the occurrence of n events on m occasions, If 
p is the probability of the event, and q (-1-p) is the probability of its mon-occurrence, 
then m events occur on m occasions with probability aCn pq ss 
This is simply the nth term of the expansion of (p+q)™. AS we've seen, the expres 
sion mCn can be evaluated approximately using Stirling's formula, so that the entire 
expression for the probability is easily calculable, using the logarithms of mCn, p", 
and q®,. Example: the provability of throwing 55 sixes in 340 dice throws is 

a4ocy. 1)? (5767799. 
The Poisson distribution models events in the sume way as the binomial distribution. It 
ja a limiting form of the binomial, as the probability of an even! becomes very small 
while the corresponding exposed-to-risk is large, A typical example is the number of 
printing errors on a page. The distribution is a function only of the mean number of 
events; the formula is 

-R on 
pin) *e¢ 


nl 
As an example, suppose there are on average 2 errors per page. (These events are 
to be Independent; this distribution won't modei road accidents, where 
there fs an obvious grouping effect). What is the probability of a page huving four 
errora? The formula gives exp(-2)024/4! = .09 . 


The Normal distribution Is important because (the result is derived from the ‘Central 
limit thearem') samples token from ony other finite distribution are themuelyes normally 
distributed. Consequently many standard statistical tests and methols embody results 
which are teue for the normal distribution, The t-test uscs observed values to estimate 
ranges of values of the porent population, the chi-squared! test estimates the squared 
normlisedt devintern from the menn (i.e. *) T); and analysly of yardince teenniques 

i] 


CANOVA’) attempt to sort out the separate influences of various fugtors - e.g. lype 
of woil and type of fertilser (np crop-yleld experiments - anmuming # Jineae model. Atl 
these methods tend themyelves lo anusnge machine applications, notably amongat 
students ln the US, where the compuler packages to pun this seg freely availible, 

Not many users of theun facilities understand the astetintical Uheorlens undertylag the 
muthods. * 

Sia Lour ezrora ware fouad in atatiaticn] packages in general commercial and education 
al use. The packages date (in part) from the mid hinntewn sirtias, 
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Non-parametric tests are relatively rough and ready, intended to provide guides where 
accurate measurement and calculation is toa time-consuming or intrinsically difticult, 

in some quality control work, for example, and when dealing with subjective ¢stimates 
or orderings, The ‘sign test’ is an instance: in say twenty consecutive fluctuating 
readings or mensurements, about half can be expected to be, above average, or to have 
a positive sign change from one to the next. A suitable warning-value can be decided 
by estimating the probabilities of 0.1,2,... variations. The ‘cumulative sum’ method 
which tests whether @ mean value is correctly adhered to illustrates the same type of 
appronch. 
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16.3 Simulation 


Computer simulations have been attempted in a wide runge of specialisations, with 
results of variable value. Weather forecasting relies on a vast amount of data, process- 
ed in vast machines. The earth's surface, or perhaps a hemisphere or other division, 
ls notionaltly subdivided into small units, and @ mathematical model employed to project 
present wind speeds and pressures at discrete altitudes within each unit. The results 
seem to be reasonably good, but not completely successful. More speculatively, math- 
ematical niadets of economies have been constructed (by economists with the appropriate 
temperainent) and are sometimes used to provide predictions. The results are not 
encouraging. Still more speculatively, ‘World models' have been constructed, notably 
by J.Forrester in the early 1970s. These rely on hypothetical connections between 
food supply, population, resources, pollution, and so on, so that each variable in 

one time-period ean be estimated, then cach variable in the next, and so on. (It is 
assumed that ‘pollution’ can be measured as a single number). Less general models 
have been constructed by companies, particularly large ones, trying to quantify the 
results to be expected if sules suddenly increase, or interest rates fluctuate, or raw 
materiats change in price, or some of the other vast number of factors influencing 
company performance come into play. ‘Operations research’, as it was called in the 
1960s, deait with some of these problems; techniques like ‘linear programming! and 
the various types of numerical and dynamic programming algorithms date from this time. 
All these techniques, except those involving heavy number-crunching, can be run on 
microcomputers, provided the user is prepared to wait, and provided also that large 
scule dita storage is supplicd where necessary. A good example of a pructicul system 
is VisiCalc, a software package developed for microcomputers on a lurger machine, 
which provides for row-and-column calculations, und is in effect a high-level language 
to input titles and mathematical formulns. 

It ls extremely difficult to judge what proportion of computer simulation effort is 
simply a beguiling intellectual game. As with any model-building activity - notably in 
the fields of polities, economics and religion - results deduced from a model by those 
with an intellectuat vested interest tend lo be trusted to an excessive extent; results 
which run counter to nelumon sense are, if anything, believed even more fervently. ° 
However, microcomputers ure perhaps less likely to lead their devotees into absurd 
errors than huge machines. We'll look at five examples of simple simulation; these ure 
too small to approach any sort of sophistication, but show the type of things invelved 
In mathematicus model-building. The first 1s a randomising routine, used for such 
purposes @s simululing a curd-shuffle, The next simulutes words by scteeting letters 
of the alphabet with their correct frequency. The third solves a well-known ‘paradox! 
concerning birthdays; the fourth is a 'Monte Caric' simulation of queue formation 
(Mine! in the U.8.!); and the dast embodies # simple bioloyicnl theory of population 
jay Forrenter's books (published by M.I.T.) includes ‘World Dynawica’ (187%) and a» 
lesner-known wark wodetiing towns, which aeaumea a basin of U.S. suburb wxtylu real- 
entatg. ‘Operutionw Aaesearch’ by Ackorf and Saptent (Wiley?) covers typleaul O.N, aethode 
and esiutiona. ‘Newer Yaen of Mathewatiow’ (ed, J.Lighthill, Penguin in U.K.) and 
"Mathematical Moteliling’ (Andrews & McLona, Hutterworthr}? offer a aurvey of methods 
and 16 examples of audelling, respectively, which are inlLeresting to the mathematical 
reader, although not partticuteriy redavent to computore, ha ia true of moat malheomat- 
lcal works, LIStho athespl is made ta determine how far the canatfucts ran be eapectoed 
lo apply is reat Life There are many bauer on ecoaometr ton amd relatind mat jectas 
MeGraw-Httl print @ muaber of them. An out-of-print tank by Andean Wilson C'The Homh 
ane the Computer’, Ikerete & Ruckli??, 1904) surveys mi bilory gamed Prom the lath cont- 
ury to the present, claiming Uhat meny Geraan vrrore in worda War Co eee the resmit of 
Inappropriate Peusstan ewarganiog, and dteaelag wtetler caonelubaisod@ BLOUt cemputar ware 
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growth and decline of predator and host species. 


(i) Random Shuffling. The algorithm used here is again the work of Knuth and 
simply selects one item ut a time, reserving it In an early part of its array, so the 
remaining items have an equa! chance of selection: 


1 REM THE ARRAY HOLDING THE VARIABLES IS PTPS(N), WHERE N 1S THE DIMENSION. 
2RSM ('PTRS' STANDS FOR ‘POINTERS’, BUT THIS ISN'T A VALID NAME). 

3 REM THE ITEMS ARE PTRS(1} TO PTRS(N), I.£. NOT PTRS(O) WHICH IS SPARE. 
4 REN AFTER CALLING THE ROUTINE, PTRS{1) TO PTRS(M) ARE ‘RANDOM’, 

§ REM TO SHUFFLE THE WHOLE ARRAY, PUT W-1 IN PLACE OF ©. 

10 FOR J = 1 TO 


20 Jt = J + RND(1)*(H-J+1)  ; REM PICK RANDOM ELEMENT FROM J+i TO THE END 
30 TEMP = PTR{I) :REM AND SWAP IT WITH THE JTH 

40 PTR(J) @ PYR(J4) 

SO PIR(J%) = TEMP 

€0 NEXT 


(ti} Word generator. The word 'Qume' wus selected from & computer-generated 
liat of ‘meaningless wurds'. The following program may help you to do the same! The 
data statements are approximate frequencies of the alphabetic characters; they should 
add to 1, (They are guesses only). Line 130 chooses A-Z and space as the options; 
the list ean include punctuation if required. Linc 209 builds an array of cumulative 
frequencies (.06,.1,.14,.18,.27,... here) which line 310 compares with random number 
R from 0-1. Thus, R=.18 to R=,27 causes line 320 to print E, and in gencral the let- 
ters occur with the correct, or at leayt the specified, frequencies. The result can be 
made more lifelike by incorporating a 'stochastic’ technique, i.e, taking account af 
previous ietter(s} yo that q always precedes u, for cxampie, or capitals only follow 
full stop and space. 


QUAS I -WORDS 


100 ALPHABETS*” ASCUEFCHIJKLMNOPGRSTUVWKYZ +.“ 

L160 PATA (Obs 047 O41 O45 OP) OFe OBr OZ) O50 + OL 005s «039+ .031.05: REM A-N 
120 DATA "05> O22 6005+ 05) O51 O74 021, Ole Ole 0051 OL ,O05r. 21REM O-SP 
130 N=27 

200 DIM PIN: FOR J=#i TG N: READ PiJ)s PisJreP¢J4+Pi(J-L)a 
30u) RaRN 1) 

310 FOR Jai TO N: IF ROP{J) THEN NEXT 

420 PRINT MIDS(ALEr J, LIT 

330 GOTO 300 


NEXT 


GH) Birthdays. Assuming birthdays are evenly spread throughout the yerr, how 
large a group of people muat be selected to ensure an even chance that none of the 
group shares their date of birth? {f.c. ignoring the year of birth). This BASIC pro- 
gram printa a table of results. Line 130 catculutes: the probabtlity p for n peuple Unat 
at least one pair have the same birthday, using the fact that if, say, 10 people have 
been chosen alrendy, the iith has a 359/365 chance of algo being dilferent, 


ALL OATES 
DIFFERENT 
ONLY NTR ENe 


10G PRINT “NUMER PROBABILITY 
104 PRINT " OF THAT SOME GATES 
108 PRINT “PROFLE ARE FQUALt 
110 FOR N= 5 TO 95 STEP 5S 
B20 Peli REM PROBABILITY [6 1 AT STARTe BUT DECREASES WITH EVERY PERSON: 
130 FOR 1 = $ TO N-1s P= Foo (3965-13 /9851 NEXT 
144 PRINT N“ "L-P" “TA CPY 
150 NEXT 

tiv) Motte Carlo Queuing Slathiliot, A 'Monte-Carko! odmulation generates 
random figures and puts Uiem inte a maded. Roulette renulls can be slinubsted iika: this 
a kyatem enn be tried out da this way, find ean be expected bo pragucs dimiba re pede 
In practice if tha: wheel da tandem. and Che Trenton: matiberrs’ are rapeitous, aaraed Gest 
experiment da eurtinued inte ‘he tong run’. The sogutpie pray ead Crot pane) mache st 
Roxltuation where cuslaners os aerved ut severct conmnterd. Theee vaerhiteless sie pope 
at othe alurt: the aversgne tine Getween custodiers, whoo are gesugmed to oarrive ovegly Ir 
the time perind sanaidernd, the stverage thine to seree a customer, and the auinber of 
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counters. All counters are presumed to be equivatent. Obviously, if the rate of service 
is too slow on averare the queve length (which i've taken here to be the number of 
people waiting in line) will increase without limit. But even with adequate service there 
will be oecasioneal queues. The program models consecutive intervals of time. For 
instance, suppose the interval taken is cne minute, and the average time between cust- 
omers is input as 5, The model assumes there is a one-fifth chance, as it enters its 
new interval, that a customer should enter. (Line 110). Line 160 models the chance of 
a customer leaving from any one of the counters in use, The program loops indefinitely 
while keeping running tetals of the time period, the number of customers processed, 
and the number of people waiting (i.e. not being served) at any moment, This output 
shows the appearance on the screen; - 
And this shows the result on stopping 
the program and entering GOTO 500 to 
see the summary :~ 


LENGTH NUMRER 


CUSTOMER OUT 

192 CUSTS: 9 QUEUE: & TOT CuST: 39 
193 CUSTS: 9% QUEUE: & TOT CUST: 39 
t94 CUSTS: F QUEVE: 4& TOT CUST: 39 


0 13t CUSTOMER OUT 

1 44 195 CUSTS: 8 QUEVE: 5 TOT CUST+ 39 
2 4 CUSTOMER IN 

3 7 194 CUSTS: 9 QUEUE: 6 TOT CUST: 40 
4 17 CUSTOMER IN 

3 i] CUSTOMER QUT 

& 1] 197 CUSTS: 9 QUEUE: 6 TOT CUST: +1 
7 9 198 CUSTS: % QUELE: 6 TOT CUST: 41 
8 ° 

F oO 

10 is] 


BUEUING THEORY SIMULATION ASSUMIMG RANDOM ARRIVALS: 


O DIM WE(100): REM ROLES BISTRKIBUTION OF. LENGTHS OF LINE/ QUEUE 

10 PRINT “CCLRICRVS} GUEUFING SIMULATICN CUGWNITBOWNI 

20 INPUT “AVERAGE TIME BETWEEN CUSTCMEFS SC 

3G INFIT AVCRAGE TIME TO SERVE"FS 

40 INPUT " NUMBER OF COUNTERS"? N 

50 PRINT “CDUWNITYPICAL NUMBERS WATTING: ~ 

106 REM «# IN ONE TIME INTERVAL’ #44 

110 IF RND{L){1/C THEN P*P+i: TRETPels PRINT “CUSTOMER IN” 

120 IF ®&=0 GOTO 140 

130 X= 

140 IF N{X THEN X=N: REM X IS SMALLER OF NO. OF PEOPLE; NO. OF COUNTERS 
150 FOR J 3 1 TO X 

160 [F P}0 THEN IF RNDO1IC1/5 THEN FeP- 43 PRINT “CUSTOMER OUT” 

170 NEXT 

180 Q-P-N: IF Q(O THEN O*9O 
190 WH(Q) = WRIGt + 1 

200 PRINT Ti “CUSTS:“t Pi 
210 T= T+ t 

220 GOTO 100 

56G KEM #® CUTO $00 PRINTS DISTRIGUTION OF QUFUES WHEN SIMULATION STOPPED 
$10 PRINT LENGTH NUMBER 

520 FOF J#O TO 20: PRINTJ: TABCO)s WH(T)) NEXT 


“QUEUE: "? Gs “TOT CuSTs"+ TP 


tv) Host parasite populatian shnutation.  Shuptifying somewhat, We con resi 
that the haak poputatiet ia given time period fneresses iy a anturid rate af inerense, 
which Is redueee: in preportion to the predater pepatation. Anat we assuine that the 
parasites dle at some natural rate, unless (here are hosts, This proKraa displays Une 
results Tolluwinss Crom the aocdel: 

100 EXPT ‘STARTING POPULATIONS OF HOST & PARASITE", H,P 

120 INPUT “RATE GF HOST INCAKASE/ PARASITE DECREASE", RH,OP 

{20 INPUT “EFFECT OF PARASITE OK HOST AND OF HOST ON PARASITE”; CI C2 

130 PHINT HP 

140 pH = (AN ~ Cie) eH: DE (-KP e C24) *P: REM LOTKA- VOLTERRA EQUATIONS 

Ib) Bo~ LNTCI ® DMs oe INTE + OP). TF IG OR BO TIEN END 

1g GAT? 130 
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16.98 Accounting and actuarial programs 


16. Mathematical programming 


The type of programming in this subsection is concerned not so much with detailed 
record-keeping, but with techniques for solving weil-defined proviems of an arithmetic 
nature. The first example is an illustration of an accounting problem, namely to deduce 
pre-tax income from post-tux income, allowances, ond reliefs. The second is an inverse 
interpolation exampic, used to solve an actuarial problem involving compound interest. 
(i) Tax Gross. Five variables are used by the program, in addition to para~ 
meters which are set within the program. Lines 10-70 holds the number of tax bands 
the step sizes of the bands (there are eight in the example) and the income tax rates 
applying to the bands. The figures given are not current. An example of the output, 
from @ CBM printer, is shown. Lines 420-462 do the actual printing: the parameters 
4.C,K,5, and T are those input; X (with some rounding and formatting) is the gross 
amount, The point about denominators and numerators is to provide 4 correction where 
part years apply, where time has been spent abroad. Lines 200-310 perform all the 
calculations; JE is a test variable which ts checked within the loop in line 250 (und in 
line 205 for low vaiues}. 
10 DATA $.@,. 750. 2258, 2803, 3008, 5000, Sag. (Ese 
26 DATAG,.25..3,.4..45-.5..95,.8 
36 READNU DIMBHCHUS- DIMRT<SNUD 
$9 FORIS1TONU 
SO READBH¢ [9 > HEXT 
68 FORI=17TONU 
70 READRT<¢ 13: NEXT 
£7 REM COWTIHUE 
2g TE=S#CR-Ks-THl 
Z2hS tPTEC=QTHEMX=A: TH=4 GCTOSEG 
21@ B= 
220 FORI=iTONU-f 
230 TE=TE-PHC 1 4#<T-S#R TC 12> 
248 BT=BT+kH¢ I> 
250 JETECSEN CT +12#CT-SHETCI +4) STHENTHERT CI tL ISHU-1 
274 NEXT 
306 X=TES“T-S#TH? 
310 X=CK+BT+C aT 7s 
320 REM END OF CALCS 


426 PRINT” "HANES 

422 PRINT 

425 PRINT . SALARY: *A 
4925 PRINT “ SLLOWAMCES AMID DEDICTIONS : "C 
432 PRINT" FELIEFS: "K 


DEMIMINATING FACTOR: "2 
HUMERATING FACTOR. "T 


435 PRINT" 
437 PRENT " 
450 PRINT 
455 X=4H 100° GOSUEIONG : K=K/106 

453 21=1 'GOSUBZ069 

468 PRINT" | GROSS SALARY? =°X" 1" 
462 Z1=2'GOSUE2H0A 


PREM og Oh ae 










1978/79 


SALARY. 14006 
ALLOWANCES AWD DEDUCTIONS 123 
FELIEFS la 
DENOMIMATING FACTOR 19 
HUMERATING FACTOR «9 


JONES 


coe 
1 GROSS SALARY = 14826.06 | 
a i cr nth 


. 
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(ii) Compound interest calculations. The program on the next page has a fully 
documented format which explains the workings of inverse interpolation. Its expression 
is a simple one; line 500 has 9 present value funetion corresponding to the value, in 
money terms, of a sum of 100 payable in a yeur's time at interest rate [%. At five per 
¢ent the formula gives 100/1.05 = 95.238, Lines 1000 to 2000 repeatedly calculate values 
until either a good estimate is found ~- its accuracy controtled by the comparison in 
line 1020 - or until it becomes clear that there is no salution. A typical output is this: 





OFFER VALUE? 95 
INTEREST RATE [S$ 5.26321411 
WHEN PRESENT VALUE = 94.9999493 


AT INTEREST RATE = 5.263 
VALUE [5 95.0001425 

AND AT INTEREST RATE = 5.264 
VALUE 15 94.999240i 


from which it is clear that a present value of 95 corresponds to 5.263%. This figure is 
easy to check by solving the equation, The partial example which follows is less simple 
to check, involving such complications as repayments several times during the year, 
the deduction of incnme tax, and payments of capital gains tax on the difference 
between the redemption amount and the offer price. The formulas are standard ones, 
recognisable to people who use them; Um not cerfoin that all the details are correct. 
Note though that the input statements and function definitions can be inserted into the 
inverse interpolation program, although, because of the complexity of the expression, 
@ subroutine rather than a function definition may have to be used in lines 1000-1040 
when each value is being computed. 


100 REM 


101 RES OEE UUSELEAOERD CSOT TUTOR OEE LEE EE 
t0z REM # # 
103 REM # VALUATION OF A FIXED~INTEREST REDEEMABLE SECURITY é 
104 REM é 


f 
105 REM TTT ed 
106 REM # ASSUMES: REDEEMABLE AMOUNT (C) 


107 REM # APTER A NUMBER OF YEARS (N) # 
108 REM # AT TRUE (NOT NOMINAL} RATE OF INTEREST, G f 
109 REM # PAYABLE YEARLY P TIM£S # 
110 AEM # PURCHASED 1/M OF A YEAR AFTER LAST PAYMENT = # 
til REM # WITH INCOME TAX AT RATE T, f 
112 REM ¢ AND CAPITAL GAINS TAX AT RATE Tl f 
113 REM # VALUATION RATE OF [NTERZST I- # 
114 REM PTITTITTITT TTL LE 
115 REX 


[20 DEF FN V(N} = (L40}7(-N): REM CALCULATE ¥ TO TRE K. 

190 DEF PN SLCP) = CC CIFD) DL) /CPACCLHL)CL/P)-L))2 REM ACCUM. VALUE PAID PTHLY 
140 DEF PN A{N) = (1 — PN VCN) )/T: REM VALUE OF ANNUITY OVER W YEARS 

150 INPUT " REDEEMABLE, AMOUNT" jC 

160 INPUT “™ AFTER HOW MANY YEARS';N 

170 INPUT " ACTUAL ANNUAL INTEREST PAYMENT" ;G <G—G/C +: REM GeACTUAL RATE 

180 INPUT "HOW MANY TIMES PAYABLE PER YEAR";P 

190 [INPUT "NO. OF DAYS SINCE LAST DIVIDEND" ;M ¢ M=M/365: REM MeFRACTION OF YR 


200 tNPuT ” RATE OF INCOME TAX"; T : T=T/100: REM DECIMAL 
210 INPUT “ RATE OF CAPITAL GALMS TAX"; TL: TL=TL/2G0: REM DECIMAL 
220 LNPUT " VALUATION RATE OP INTEREST’; £ :fes/100: REM RECIMAL 


300 fF Pel THEN PY © (L461) @ (CMFNY(N) + GAC LT) RCRPNA(N) = TI(C-A)*FNV (ND) 
JO IPP<>ITHEN P¥=(LeT IH & CCAFRV(N) + GCACL<T}AFNSL(P)PCAPNACN) ~ T1*(C-A)*PNV(M)} 


1 neve Insufficient apace to consider problema of life aanurance, life table calculationa, 
ete. In detail. A major difficulty ts the need to store large amounts of tnbular dita; 
yume life tnblea have been eaiculeted da the fori: of pmouthed formutaa, uannily three 
ar oau curves which, Between them, caver the entire aye span, if such ow formula fs 
Conaidered accurate, naturally there ina great aiving ln aforige space (though aot la 
computing time, probably y In cateulating eich value aa tt $a fended. | have no lnforma- 
ten on the extent of smait computer use in the inaurance world, Ubvioustly the com 
panies Invelyed uae mainframes for mlorugs of their bulk data; perhaps aioull machines 
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oO REM 
L REMPSFPPPEFEIIRESARCHEDT TE FOS ZERRAOERER IDS S CIEE OEEERERLS ACIS T ETAT ERE RET CREE TET 
3 bet INVERSE INTERPOLATION DEMONSTRATION USING A PRESENT VALUE FUNCTION. #f 
rc 
ea 
& REM#) METHOD: BEPEATED CALCULATIONS, USING A BINARY CHOP, CONVERGE TO THE #¢ 
5 REM@#? CORRECT VALUE, ANO WHEN WITHIN AN ARBLTRARILY SMALL AMOUNT OF #2 
A aoe THIS VALUE, REPOAT THE RATE OF INTEREST FUUND. fi 
» é 
& REMéF LINES 500 - 1040 PERFORM THE MALN CALCULATIONS. ## 
D REMPSSPPISISPREOAEERAOFEDSSERLI IVER OREEASPCEERAC RHE TEAK DATE ORR RRS OT ET RR TERS ES 


10 REM : 

500 DEF FW P¥(L) = 100 / (i+ 1/100) : REM 
600 INPUT "OFFER VALUE"; V 

700 IL = -tO: LH = 50: REM CHOOSE -102 TO 50% AS LARGEST REASONABLE RANGE TO TRY 


VERY SLMPLE PRESENT VALUE FUNCTION 


980 REM 
BL REMEMESRRSHEAAALERER AED TODA GERAEAREEOETEGGERERGEC EHP EGHE CATR EGSOEEETE CROFT 
932 REM# INVERSE INTERPOLATION CALCULATION BEGINS. # 


O83 REMFPAEMOTHAAPPEORASHESSALEIIHSATIARL OP ELORE CRE ERLIC ATES OR TRA ESOS IO CHEED SE 
984 REM# NOTE:?) LL AND IH ARF LOW,HIGH ESTIMATES AT EACH STACE OF ITERATION, # 


985 REW STARTING AT -10% AND 50% TO BE SURE Tur CATCH MOST VALITES. f 
986 REMF 2) AS INTEREST RATE “1” INCREASES, VALUE DECRFASES; THAT’S WHY # 
987 RENF THE TESTS CM LINES 1030-1040 CHANGE LIMITS THE WAY THEY DO. # 
988 REM# 3) INTEREST RATES APPEAR AS NORMAL EG 12%, AND NOT 0.127 
989 RFM? 4) LIMITS IN 7O0,ACCURACYIN 1020,DEC.PLS.IN JOLO,ARE ALTERABLE. # 
cd ed LE a a lc laa 


1000 IF IL = IH THEN 2000; REM OUT OF KANCE OF START VALUES - CAN’T BE FOUND 
LOL0 BEST = (IL + IH) / 2 : REM AVGE OF LOW AND HIGH RATES LS BEST ESTLMATE 
1020 If ABS (FN PV(BEST) = ¥) < 1 E-4 GOTO JO0G: REM CLOSE APPROXIMATION FOUNU 
1030 IF FN PV(BEST) < ¥ THEN IK = BEST : GOTO 10G0: REM “BREST TOO HIGH 

1040 IF FN PV(BEST) > ¥ THEN IL = BEST : COTO 1000: REM “BES'C’ TOO LOW 


REM 

LOOL REMPSORTESORAHERRI EMRE ELSIF CERES TAO T RRR CARH TR REED dope 

1992 REM# REPORT HERE IF THA INILKEST RATE LS AN eee ie SroRUNGe VALOE 2 
et Meee ee ee ee tN etre Crrcne na cen teehee nt 
-2000 REM NOT FOUND -~ RATE ELTHER LESS THAN -19% OR CREATER THAN 502. 

2010 PRINT "NOT FOUND = "; 

2020 IF BEST = -10 THEN PRINT "RATE IS LESS THAN -102" 

2030 LF BEST = 50 THEN PRINT "RATE EXCEEDS 502" 

2040 PRINT: PRINT 

2109 GOTO 600: REM CONTINUE ~ INPUT NEXT VALUE 


REX 
2991 WEMPPPPPAEPAEEPESFEERSELTOEEEEPAD GATT OMITEL ATER LETH S ORS ERP ERDAR OI TIE 
rhe _ REPORT HERE WHEN VALTO INTEREST RATE HAS BEEN rouND. . a 
REM 

¢ 
2994 REM# UNROUNDED RATE AND TWO VALUES (FORK 3 O.P. RATES) ARE PRINTED OUT.# 
Hee EU/FIEIUAGGHUSATO4QTEAFITOCOTADUSIFOGATOGESIILT4GBEEDOF0T00b 800000309 
3000 PRINT "INTEREST RATE 5°; BEST 
3010 PRINT" WHEN PRESENT VALUE ="; FN PY(BEST) 
31020 PRINT 
3030 L » INT (1000 * BRST) f 1990 s REM THIS TRUNCATES TH® VALUE T + PL. 
3040 PRINT "AT INTEREST RATE ="51 ape ee 


aie Zs VALUE [S "; P¥; “[LEPT]." 

INT "AND AT INTEREST RATE ="; 14+.f01 : REM NEAT ¥ . * 
JO80 PY = FN PY(L + .O01) Den age nen re 
3090 PRINT “ YALUE IS "5 2%; “[UEPT]." 

2100 PRINT: PRINT 
poine GOTO 600: REM CONTINUE = INPUT NEXT VALUE 


et 
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26.5 Triggnometry 


CBM machines all have sine, cosine, tangent and arctangent as standard. These were 
presumably taken over from FORTRAN by Microsoft, rather than specially written. The 
three angle functions ail call the sine routine; tangent is calewated by dividing sine 
by cosine, and is therefore likely to have larger rounding errors, and be slower. The 
arctangent is quite useful in some analytical problems, since its range covers the whole 
real number spectrum from minus to plus {nfinity. This is a result of the fact that the 
tangent of an angle is the ratio of two unrelated sides: their ratio therefore cnn take 
any value, unlike sine and cosine. Trigonometrical functions typically nave uses in 
engineering, surveying. perspective and drawing calculations. Each function relates 
two sides of a right-angled triangle to an angle, see Chapter 5. Since there are 3 
sides, 6 possible ratios exist, which are, using the shorthand H=hypotenuse, A=side 
adjacent to the relevant angle, and O-opposite side, 


0 A Q t H A 
Sines Cosine=y Tangent=, Cosecant=5 Secant=) Cotangent=, 7 


Most of this will be known by readers of this subsection already. It is worth recalling 
two simply-drawn examples which provide practice in these functions: the first is an 
equilateral triangle with sides of length two units each, and the second a right-angied 
triangle with two other angies of 45° and sides 1,1, and 1.414 (=W2). Then retation- 
ships involving angles of 30°,45°, and 60° gre simple to check, e.g. tan(49°)=l, 

eos (60°). 4. 

All of these functions are defined so that lines may be considered nogative in 
length; this convention supplies the familiar repetitive sine curve with theoretical , 
foundations. Some vaiues, 0°,90°, 180° and sq on may give trouble in evaluation if 
division by zero becomes a possibility. We shall see how to program around this, and 
make the calculations crashproof. A potentially confusing point about notation is also 
worth clarifying: the inverse sine function, which gives the angte corresponding to a 
sine value, and which is called the ‘aresine'., is written as sin™4x. This is easily con- 
fused with the reciprocal of sin x, which is (sin xc}. 


Crashproofing trig functions There are three methods; 

{i) Request the user to avoid values known to crash; typicaily 90° or 0° may 
have to be avoided. 

Gi) Test the values input and disallow those which erash, printing cither an 
error message or @ known correct value instead. Often an expression can be simplified 
in sone way: for example sin x/sin 2x will crash jf x=0, but the expression can be 
shown ta equat 1/2cus x. which Is troublefren when x=0. 

(ii) A more thorough implementation of (ii) modifies the function itself so that 
extreme valuvs are replaced by values almost identical, and yielding the cerrect solu- 
tions, but protected against crashing. SIN{X * {X=0)*1E-9) in place of SIN(X) sub- 
stitutes SINCIE-9) for SIN(O) if this function appears in the tower half of a fraction, 
for example. A Letter example is provided by this erashproofed expression for arccos, 
which usea the relation ARCCOS(X) » ARCTAN(X/SQR(L-X?)) ; 

$00 DEF FN AC(X) © ATN(K/((R#1) “12-9 + SQRCA-XON}I) © (-1LITCM+1) + [PE }eNe (PI) 42 

410 DEF FN DC(K) «© FN AC{X) © 140 / {PI] :REM ARCCOSINE OF X IN DEGREES 

200 FOR N « 0 TY 10: PRINT FN DC{Q): NEXT 


The example prints 90.270, 450,...1710,, 1890. 


Trigonometric equations A typlent textbook general equation for solution fa: 


asain x +b com x et 
Iby divining theouprh wlth agra +b?) and using an expansion of eostp eq). we aun 
calutlish the general solution as 


x om arecos (e/sqrat ebT)) - atn(-D/ad. 


10 ORF FN ASOR) + C-GaTH © ATN CH/RQRCI-KONDD + [Pl]eN 7 REM ARCSENE 

20 DEY FN AOL) © CPE) s2 > FN ASKER) AEM ARCCON DEFINED TN TRIAS OF ARCHIN 
100 CNPUT “a, h,e in wo sans + Bb com x EG A,A St 

110 FOR N « -3 TO 4 HREM PRINT A GPECIMEM IKAAGE OF BOLUT IGN 
J2t) THETA = FN ACCU, SQRIASASHPBD + ATMC-H/A} 

140 THETA « TERTASIAOGS{ FA): PRINT THETA “URDREES: MEXT 


cette A ae, ce eager eet a ra etd Ne 
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Fisiell 
REM 

“oRTM ean 
t REM 

QO GER FN SG1l4x2 = SINCX#FI/180)} = 
O DEF FN COCK) * COS(X#F1/180) ;: 
U WEF FN TAK) 2 TANCXHFI/ 260) 3 


FUNCTIONS OF ANCLES [N DEGREE #4” 

REM CALCULATE SINE GF ANCIL.E IN DEGREES 
REM CALCULATE COSINE OF ANGLE IN DEGREES 
HEM CALCULATE TANGCNT HF ANGLE (IN DEGREES 


9 REM 

OG REM #€* INVERSE TRIGONOMETRIUAL FUNCTIONS (RADIAN) ta 

OL REM 7 

iv LhE FNM ASOCX) = ¢-19°N & (ATN CLCGORCL-X80)) 2 + FI®N : + FEM ARCSIN 
“0 OF FN AC(X) » PI/Z-(-L9°n * (ATN (X/SQRC1-X4#X)) 2 + PI*N ¢ REM ARCCOS 
wy DES FM ATOX) = ATNOEX) + PLEN  : REM GINERAL ARCTAN 

797 KEM 

ter REM @** GNVERSE TRIGQNOMETRICAL FUNCTIONS IN DEGHEES #R* 

‘al REM 

iw DEt Fx US¢k) = FN ASCX) #1GN/F1 + KEM ARLSINE OF X IN DELREES 

‘20 FEF tN uctx) = FN AC(X)#160/F] + KEM ARCCUSINE GF X IN CECFRERS 

ge DEF EN LTGX) = EN ATORD a2 U/ER FEM ARCTANGENT OF X UN UEGIKERS 

99 REM 

Oo REM #e*e FURTHER INVERSE TRIGONGMETRKY FUNCTIONS #¥e 

1O1 REM 


* ARC CUSL1/X) 
* ARC SIN(1/X) 
= ARC TAN(L/X) 


lu FEM ARC stO(X) 
Zt REM ARC COSECCS! 
Servier BA 6 TORS 


16.6 Arrays and Matrices. 


Definitions and rules of manipulation A ‘matrix’ in the mathematical sense is a two- 
dimensivna! array of numbers. In BASIC these can be conveniently stored as A(R,C) 
say, where R and C represent the dimensions of the array and mnemonicully suggest 
the order rows then columns, which is the usual convention. Matrices may be manip~ 
ulated mathematically in several conventional ways. Some BASICS («.g. [BM's) have 
their own MAT statements to facilitate this, but Micresoft RASICs normally don't , 
presumably because of the comparatively smal! demand. There are difficulties in imple- 
menting commanda of this sort in any case, because of the need to reduce rounding 
errors when dealing with the very liurgest matrices, and becausc of the memory ras 
quirements. 

The reasons why matrices cun be useful aren't especivily eas 
The best point of entry is probably to look at wmuleaseoua aaontions- ee 


a+ 10b + 160c = .03 
a+ SOD * 2500c = .29 
a + 1000 + 10000c = .98 


Here wo have three equations connecting three unknowns, a.b, and ¢c, Smalt sets of 
equations Nike thia one can be solved quite quickly by comparing pairs of equations 
and climinating unknowns, The interpretation of these equations, in conerete terms, 1s 
not too difficult; fer example, o, b, and ¢ may represent weights In grams, and the 
three eombinations of ong of the first type of itum, len of the sceond, atid ane hurid- 
mat of the third and so on plus the respective weights muy have been deterninert 
emplricully. Solving the equntivas gives the weight of euch type of item, Another 
wample: suppose an egg + two pieces of bacon costs 7% units, whibe an eye + one 
pieces of bacen costs 50. Ansuining the costh are straginttorward calentitions. aivircic 
wyunlions represent the sitwuetion: j - 


pe + 2ph * 75 
pe + ph = 50 


And of courde the two pricea pe and po are 29 unlte wach, Matrices deal with situa: 
tlonk of this sort by sepnratlag oul the block ef factors from the blosk of variales 
and the rulea af matrbe ndilithod, sol-fracdion, died quttiplicatiog are aede cignaudinil: 
with this achome. Consequently, matrices ara usable whenever culoulationn of this wrt 
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eccur: in economics, attempls are made to construct matrices to mode! flows of raw 
materials and made-up goods between industries; price x quantity calculations may be 
made;* predictions and deductions about migration, genetics, and so on may be made. 
The idea ix always similar to that embodied in our simultaneous equations. We can 
represent the first of them in this way: 


1 10 100] [a] f[.03 
1 50 2800] +] >] =) .29 
1 t00 10000, |e 98 


Which may help to clarify the idea of matrix multiptication: the point is that the row(s) 
of the first matrix are muitiplied by the eolumn(s) of the second and added to give the 
corresponding elements in the third. For this rerson multiplication is meaningtess if in 
ACR.C) * BCR'.C') the value C is unequal to R'. Division is not defined directly. but 
is implicit in the idea of multiplication: a square matrix holding only zeros, except for 
its top-left to bottom-right diagonal which holds ones, is called the ‘“dentity matrix’ 
and corresponds to 1; any two matrices which multiply to give this are enlled ‘inverses’ 
of each other, so each is something like the reciprocal of the other, as the name 
‘inverse’ implies. As we shall see, matrix inversion is a standard operation required in 
calculations using matrices. Adding matrices is simpler: the matrices must match both 
in the number of rows and the number of columns. Each corresponding element is then 
added, Subtraction is zimilar. 

Aithough column vectors (there are two in the matrix equation above) are often 
used in matrix multiplication, the generalision implied in the comments on the identity 
matrix and inversion enables any matrices of form A(R,C) and B(R',C') to be multip- 
tied, provided C-R'. For example, these 3*2 and 2*2 matrices give a 3*2 result:- 


1 oO 1 #1 
4 3] * [2 |. 14.64 
2-2 +2 2 


Matrix inversion and simultaneous equations By wuy of preliminaries, let's first see 
how to input and output an entire matrix, without worrying too much about format: 


O INPUT "NUMBER OF ROWS, COLUMNS”; B,C: Dim A(A,C) 

10 FORX = 1 TOR: FORY¥Y=1TOC 

20 INPUT A{X,Y} /RZM INPUT ONE ROW AT A TIME, READ ACX,¥) ALSO USABLE. 
3 NEXT Y,X 


500 FOR X= 1 T0 R: FORY = 17T0C 
510 PRINT A(X,Y); :RFM PRINT ONE ROW AT A TIME 
520 NEXT Y: PRENT: NEXY % ‘REM NEW ROW ON A NEW LINE 


Lits also see how to multiply mutrices; this is necessary for several purposes. includ- 
Ing the testing of programs; 


400 REM MULTIPLY A(R,C) BY B(R',C') GEYING R(R,C') AS RESULT 

410 FOR $= 1 TO C1 :REM RESULT’'S COLUMNS 

420 FOR J = t TOR ;REM RESULT‘S ROWS 

430 FOR Kw 1 TOC REM COMMON COLUMNS ANU ROWS 

440 ACJ,1} = RUT) + ACI, K)*HCK, 2) :HEM SINGLE ELEMENT ADDS TOGETHEH C PRODUCTS 
450 NEXT K,J,1 


Note that a matrix multiplication where the second array is a column, aa in the exaimpic 
at the top of this page, the outermost lwop {a redundunt, and can be omitted when for 
uxumple the solutions af aimultaneous equations are check] by substitution Inta the 
original equations. JF a row array is multiptied by a column array, the result fs a 

}x Joarray; in thin case omy the innermost leap ia required. 

The two matrlewy feuch 40 Fo ure inverdes of ench other; when multiplied, 
Irrespective of the order of multiplicailon, the result, allowing far ronndingt erracs, is 
the 4.x 4 identity, eon4isting of ds In the leading dinganal and O4 vlyewhere, We ern 
mays How th simultaneous equations, by prenattiplying 


Be fee andlor 28 sere See Se 


“S1 is taportant te hawe a cleur idea of theo” ec oraquirements and processing times to 
eaprclh with matrlian, Althougn tansy peralt vahawsl byw colculationg ¢® be made, «ren 
(e.g. In nconomit: metata) most ed the elemenia aes cero, which avec rather waoateful. 
One of Gerry Weinherg’ a etortden Cin ‘Tha Paychology vf Computer Programating'} an thin 
subject operagate how an wigapladtion a aebole pring ptructure, fa he used in (ryote ing 
wic,, wan te he held in an array, It turned out to be loa beg for the marine. 
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12 3 4 .78277) 0 -, 22647 =,24722 0 - 0054058 
0 12 4 0] 2. 4| .coozess9 .o83i0a 00029949 -.00059898) 
-1 -5 -7 12 ~.00089847 -.0002246% -.90089847 0017989 Te eros: 
662332 025583 062332 00033693 


o O555 8 


both sides of an equation involving arrays by the inverse of the (square) array which 
holds the coefficients of the equations; if A is the array, so for example 


*} to 
d t 


ef” |zo| ?” 
a| L° 


then on premuttiplying we gét these results: 


a} a6) 100 0} i fio} E 10 
~1 bj 2 al ya 0100/,/> -t da b] aT yf 
AU ANETTA Mal lao aol el “A “no, 4 cl7 * “10 

a La 0001 ls tol ta ol 


So the solution of these equations: 


a+ 2b + 3c + 4d = 10 
12h + ac 2 J 

ea ~ Sb - Jo + 12d = 10 
$55e + ad = 0 


can be found by premultiplying the column matrix by the 4x4 inverse at the top right 
of this page, giving a=4.827, b=.089d0,c=-.01819 and d=L, 262. 

A great deal of work has gone into finding and improving mzthods of matrix 
inversion to maximise speed and accuracy of different types of matrix. There is no 
room here to begin to summarise this work. Instead, [ shall develop a program using 
a mundane algorithm for inversion, which should be usable for quite a number of 
purposes,* It is not particularly elegant, but it docs work. We may as well note at 
this point that not all square matrices can be inverted; those corresponding to sim- 
ultaneous equations which won't solve, either through inconsistency or insufficiency of 
data, have no inverses. For example: : 


x 4 2y = 10 
x+* y = 10 


x+y = 10 


und 2x a2y = 20 


have non-invertible matrices. Some matrices are described as 'fil-conditioned', by which 
_ig meant that their inverses exist, but are sensitive to amall changes in the original 
piatrix, so the inverse tends to have lerge errors in its elements; the matrix 


1 i/a iv3 1/4... 

1/2 1/9 1/4 1/5... 

[2 1/4 1/8 (1/8. 
provides an illustration. 


The matrix inversion program (in BASIC; see next page) uses row operations to 
convert the original matrix M(R,R} into the identity matrix, Identical operations are 
carried out un the identity matrix. The result is that M becomes the identity matrix 
and I(R,R), the dupilcute matrix originally holding the identity, Is transformed into 
tne inverse. M goes through these stayes: 


7 re a 
nex lax fix x| 1¢c0 
xX tix G1 xj aia 
XU ti io 9 | ond 


The progesm has four parts, cxvluding the input routine and any printout and for 
checkiny routines, 

(1) Ldner 100-260 conntilule «a lnrge loop which carries out the firat two stnyes 
In the dugram abuye, Lines 100-)78 perforn divisions to convert the leading sHagensl 
Inlo la, while 


Sponald Alcock C'lustrating BASIC’) hew a shorter program which uses Gaussian olin 
ination. COM and othor Micrnaoft BAXICs mead to ada 405 IF fel » M THEN GOTO 430 
to thie progrem, since Alcackh he@ annuaed wtandard Dartaouth BASIC Joup handling. 
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COMPLETED MATRIX INVERSTON PROWRAM 


10 INFUT"LHIM' IN 

12 DATA 2626304207 126420--1) -Ss-7412+0008555:8 

12 DIMMiN+N) > TiN> ND 

13 FORY=1TON: FORX=1TON:REAQ MCX+¥):NEXTX-Y 

14 FORY<LTON: FORXSL TON PRINTM( Xs Yo R eNEXT! PRINT: NEXT 
16 FORX=ATON: 1¢X,X}21sNEXT 


2100 FOR X = 1 TON 
110 FOR ¥ = X TON 
120 D = M(Ms¥) 4 
130 FUR K * X TON 
140 CK} = MCKAY) /0 
141 NEXT K 

142 FOR K * 1 TON 

156 ICKe¥? = £(Ks¥9/D 
160 NEXT K 

1?7G) NEXT ¥ 

180 IF xX=N COTO 270 

190 FOR Y = Xel TON 

200 IF M(Xe¥) =OTHEN 250 
210 FORK=xXTON 

220 Mi Ks ¥>=M( Kp ¥>-i Ke X} 
221 NEXT K 

222 FOR K = 1 TO N 

230 [¢Ke YI) a] (Ke VI-1 CK XD 
240 NEXTRK 

250 NEXT ¥ 

260 NEXT X 


IF D=0 OR Del GTO 1790 


FURX7LTON: [EM(Xs XP =L THEN NEXT 
If XQON+1LTHENPRINT’NOT INV“? END 
FOR X=N TO 2 STEP -t 
FOR YeX-1 TO 1 STEP -1 
O=M{(xX>¥) 
FOR K = XTO N 
MCK, YD =M(Ke ¥) 
WEXT K 
FoR K = 1 TON 
Tike ¥owltKe ¥) - FCKeXP¥D 
NEXT K 
NEKT ¥ 
NEXT X 


270 
271 
272 
260 
290 
300 
3190 
311 
B12 
320 
330 
340 
3590 


~ MCKe X)*0 


Depending on the atructure of the original matrix, inversion takes something like 30 
seconds for a 10 by 10 matrix and 4 minutes for a 20 by 20 matrix. A 32K machine 
can handie matrices of ubout $$ square, leaving no room for anything but the inver- 
sion program, With BASIC at | MHz thls takes about three quarters of an hour. 

The program can be tested by (i) Inverting a matrix with a knawn inverse; the 
Identity matrix should invert to iiaetf, with some rounding error; Ci} Reinverting a 
matrix, and cheeking that the reyuit is close to the original; or (ii) Multiplying by 
the origiial and checking Unat the answer is simline to the identlty matrix. 

Applicntivuns of the technique to simultaneous equations include the calculatian of 
confficlenth of regression aqualions in statistics; many more variables can be handled 
then are practiable by manual eslewintlon, Typleally this any be useful when nt 
alyebraie curve is to lie fated to data collected by experiment. Anather exnmple Is ia 
the solution of ‘aver ccbtermined’ sinullancaus equatians, where thera are many obser- 
vations of empirical material invelving anty a few varisttun. Suppose you tave cells 
ef output Involyang unita of raw malerial whieh have been uned dn diferent combina 
tlong; say a sheet uf timber has been made Inte 15 lhems of type A, 109 of type DB. 
And Woof type Cy ad eesalts are avaliable Uke Chia for 100 shorts. Who in the lest 
enUmalie of te amount uses per type af Rem? Pechapa figurea ara avatlabh: of Uhe 
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weekly output from a group producing a mix of different size items of the same type. 
How can you estimate (for sensible pricing) the time taken on size 1, gize 2, ete.? 
One method is to premultiply both sides of the matrix expression by the transpose of 
the matrix; the result provides the best least-squares estimates of the variables! values. 
This simple case illustrates the method: 


16; Mathematical programming 


4 empirically 2xe*y=8, Correapund to fy 2 [al 
obtained equations: xty=?, this matrix “la 2% xh l7} 
Qxeyo9, arrangement: {2 aby)"|a) 

Li 3 





x+3y926, 
As it stands, this is insoluble; the least-squares sotution, however, is obtained like 
this: 
[2 12if2i 21211 fe} oe 
bia 1 ilfa] riral || which ILO el fs] . fer 
21} y¥1 9| simplifies to: [8 wzjly| ~ 142 
213 6 


and this matrix expression is solvable. Estimates of the error in the result can de 
calculated. This is, of course, only one of innumerable mathematical techniques which 
are available. it is # relatively easy one to program. If we set NE-number of equxtions 
and NV-number of variables, this routine calculates the square matrix $ which results 
from the multiplication of the transpose of M by M itself: 


1000 FOR ¢ = i TO NV 

1010 FOR R = 1 TO NV 

3020 FOR K = 1 TO NE 

1030 S¢R,C> = S{R,C) + MCE, R)*M(R,K) 
1940 NEXT K,R,C 


36.7 Number Theory. 


Number theory typically deals with large integers; these are available only with 
specially-written routines in Microsoft BASIC, and as the subject is not of wide inter- 
est, | shall iliustrute a solution oniy of a smajl-scale problem, using BASIC to assist 
in the sotution. The problem is: find a telephone number (of 3 digits followed by 4) 
which, if the first pact is subtracted from the second, and the result squared, equals 
the original seven-digit number, 

T.e. put xrabe, y=ghjk in form. Then we have: 

(y-x)? = 10000x + y. There are ubout 999*9459 combinations which could be test 
ed. (The precise number depends on whether a number like UGD counts). This will tuke 
along time; probebly a fuw weeks on the computer. Uowever, a fittle algebraic shuff- 
ling (solving a quadratic for y) produces thi: more severe restriction that 

40004x + 1 must be a perfect square if the equution is true. 


10 FOR X<0 TO $99: REM TEST WHOLE RANGE OF PAEFIX NUMBERS 
20 ¥=40004eK +°1 : 

30 IF ABS (SQR(Y) - INT(SQR{Y)) « .COl THEN PRIXT 1 

40 NEXT; END 


This program isn‘t too long in run-time. Line 30 tests for exactness of the square root: 
the range of ¥) ig about 200 to 6000, so the teyt should adequately serecn out wrong 
values, The actual form of the lest isnt really important; the point ls lo yet some 
figures, which can cnsily be checked. In fact, onty 120 prints on the serean, and the 
solution js 12 1216. 


16,3 Curve fitting, 


Least squares methods The object of curve fithing fu to discover some fairly simpde 
formula to represent empirienl data; the poink bio te gt the representation inte a feria 
whieh Is easy to handin, rather than (say } aa ou grap of a tebte, The Cechmiques 
are well known; related tapica inciuda regrenwiion apa) carreiation, lie Sormuliat of wraith 
npe alse eendily available ino tetveaka, Ther dest squares formula, ty We briefly e% 
Plalned here, Is a process which enleuletes cocflieients of a taser escpresalan whieh 
minimise the sum of squares uf predivGeal apd aeduab posiits. Ceiaudl ye eee attanpet a% 
mado ta determing a fikely form of a funetion, which is than flied ta the data ond 
checked fur aigaiflesnee. This proceaa can be nutomated partiily. Thery bs a BASE 
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program (‘CURFIT') of Jim Butterfield's which fits data to several types of curve and 
reports the results, 
The least-squares method starts with a tinear function: 


year bx, * cx, + ax, +... + fandom error 


Where xp, can be for exampte x? or log(x) or some function of x {although this makes 
error estimation more complex). For example, functions of the following types can be 

represented like this, in some cases using transformations to convert some of the data 
items into more usable forms: 


straightforward linear relation, 

y= a + bx + Cz linewr relationship with 2 variables, 

y = b/x + a + ox + dx? whero x =1/x, and x,=%}, 

y = kxyz* where a ogarithaic conversion 18 needed, which gives 

log y = log k + log{xyz?), or y' a ae x’, with only ono constaat to compute. 


y= a + Bx 


The mathematics involved in coriputing the best estimates of the constants is thia:- 


For euch observation, the difference between the calculated aad observed values 


is error = (y + mw > bx, - cx, - dx, - .-.) 
So the sum of the squares of the errors, which we will minimise by our choice of a,b, 
C, «++, is Bly - a ~ bey - Cx, ~ ax, - sd. 


The minimum occurs shen the partial derivatives of each with respect to a,b,c,., 
are all zero, 


2 


So rT Zty - a - bE - 1. )? 20 or Zly - a - bay - -..) 80, 


= X(y - & - bey - vee) P xd 
and #0 on. 

As a couucrete example, not too long, consider the linear relationship where two 
variables determine the answer, of this form: 

yz a+ dK cz. The procedure ahove gives: 


rs 
a.n + dix + ciz = S¥ 
> 
- 


oréxy(y 7 a - bey - «.-)=0, 


aix brx? + ckxt = Ixy 
aiz bing + ciz? = Lyz 


With manual methods, vatues of x and z and the result y are tabulated, along with 
the products xy, xz, and yz. and the squares x? and z?, The column totuls give the 
figures for insertion into the simuitaneous equations, which can be solved by matrix 
inversion (giving results identical to the transpose multiplication method). 


Other methods Other methods of curve (itting. adupted for less well-behaved fune- 
tions, tend to be lexs easily computerised. The easiest methods assume that a formula 
in exact, und calculate parameters accordingly, perhaps averaging difterent estimates. 
For example, suppose y=ma* + ab® is to be fitted to data on martality. Any four 
equatly-spaced sets of x and their observed y values correspond to exact vnlues af 
m,n.a, and b. The ratio of y(lyy(3) - y(2)? and y(2)y(a) - y(3)? can be shown to 
be ab, and hy algebraic juggling values can be extricted from the data. In practice 
graphs are plotted and the results tested for adequacy of fit. Another example: 

to fit dala tu the hypothetical underlying curve oy sa + bx + ed* we cun use the 

atio of y(4}-2y sy (2) to y(3)-2yf2)ey(1) to estimate the value of d3, In exainples of 
this type the ini! algeles is probnbly easier to do imunually than by computer. Other 
upproximate methods exist, some of them dating from the days before the getierul 
availabilily of computers, but Unere is not sufficient spice here to deal with them. 


- 
Lape ET EY APR PL ETT OR ENA RE tne Some eT 


Fe TRE TL rn, RR eT 





Progromming the PET /CaM -a64- 
16,9 Machine-code programming with mathematics. 


The floating-point accumulators and BASIC number storage We have seen (16,1) how 
humbers ate stored in BASIC and in tables in ROM, in 5 bytes of form exponent + 
sign bit + the rest as mantissa. Calculations ere performed by Microsoft BASIC largely 
in two locations, calied the Moating-point accumulators. The more important of the twa, 
‘Floating-point accuniulator #1‘, which we can cell FPAcc.#1, occupies $5E to $63 in the 
zero-page of RAM. (in BASIC 1 the locations are $80 to $B5). Floating-point accumu- 
jatar #2 occupies $66 to $6B ($88 to $BD in BASIC 1). Each accumulator is thus six 
bytes long, one byte longer than variable storage. The arrangement of bytes is very 
similar in each case: 


16; Mathematical programming 


Floating-point accumulator #1 Floating-point accumulator #2 


sse| $5F_ [360 [36x sob [$67 [sea | sea [ sea] s6B 
exp Torrens EXP | BITewil wz [Ma | 4 [| SIGN 


The sign byte is to some extent independent of the high bit in Stl: if they are both 
set (i.e. sign byte has its high bit set, typically #FF) and the high bit of M1 is on, 
the number is considered negative when it is transferred to other parts of RAM. In 
addition to the bytes shown here, there is an overflow byte and a low byte used for 
rounding. Most of the results of calculations are stored in FPACC.*1; the other accum- 
ulator typically holds the number to be added or multiplied. Immediately petow the two 
accumulators are 10 bytes which store numerals from RAM; these are not used in the 
same way for major calculation, These accumulators held numbers with the mu«imum 
precision available to BASIC. As we have already noted, some calculations are intrins- 
jeally less accurate than others: for instence, 7*7*7*7*7*7"7 is evaluated exactly 45 
40353607, because the integer is held without error; put 719, which uges an inter-~ 
mudiate stege in caiculation of finding the logurithm of 7, emerges ag 40353607.1. The 
accumulators’ contents can be watched by programs similar to those in Chapters 2 and 
13. is there a method ta determine the value hela in floating-point form? Not surpris- 
ingly, the enswer is yes, and the following routine is a simple way to program it. The 
routine is relocatable, and the version below, for BASIC 2, starts at $U334. In this 
case therefore SYS 826 runs the routine, which prints a flashing cursor and awails 
the input of four hex bytes and tne ‘Return’ key. [t prints the value of the 5-byte 
number atarting at that location, For example, the following four values, which apply 
to BASIC 2, come from o table which BASIC uses to calculate £0G: 


O8Ccs 1 

DSCE .494235042 
B80} .576584541 
D808 .#61800759 


1, 033A 20 B6 27 JSR SE7BS 
+, 0330 a8 TAY 

+, O33E 20 B6 27 JSR SE7R6 
-, O141 20 AE.DA = JSR SDAAE . 
+, 0344 20 £9 90 «JSR SDCE9 
+, 03467 20 10 CA JSR $CAIC 








:3E7K6 inputs a hexadecimal byte (e.g. Ad) 

; into accumulator A. 

sS$DAAE moves 5 bytes pointed to by A (low), 
Y (high) into FPAce. st and unwréeps 
tho sign byte. 

i$DCES9 converty FPAce. #1 inte an ASCIL string. 


+» G34A ad Ob LDA #$UD s$CAIC prints the string. 
a, 9340 20 O02 FP SSE $FFLE +SEFD2 prints curringe return. 
+» G34F DO Bg BNE $0314 


t O}33A 20 BG &? Aad 20 Bo BF 20 
et 0142 AR DA 20 EY DC 20 10 CA 
+3 O744 A9 OD 2f) D2 FY BO KY 


. 


Pressing the Stop key will terminate the loop. The routine can be used from within 
the monitor, by changing USKCMD or perhapa mure alinply by changing «ome command 
which jn canparatively ttle used Ina RAM aattitor fe.g. Extramon) ta point te thls 
routina'a Binet instead, The BASIC a veraton is this: 


»t O27A 20 4) D7 AR 20 43 D7 20 
: QO282 DA CC 20 943 CF 20 ID KB 
1 Q28A AD OD 3 Da FF DO EY 


, 


ONE Sc gOS IP aL paral A TR A Rey ME TW ER OE RET mt Ag mee rem Me EE 


; 


wes ie ent. - 


a ee re ae a a Nt ae = 


= ee 


ven 


ae 


rn 


. 
* nme 
ee ae pt ne cmeeten o netn ptemme Tegrenss che Cama Yel ann fet rei = = a pu ma 
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Hexadecimal to decimal conversion and vice versa The machine-code programs which 
are presented here can be called either from BASIC or from 4 machine-code monitor. 
Some versions of Supermon have a rendy-made N command, which is normally disused, 
pointing only to the start of the monitor. For example, if Supermon when loaded in a 
BASIC 2 machine has a table near the end of commands (TFHD etc.) which include N, 
then search a little further forward for a 2-byte address pointing to SFD55. Change 
this to $0339 (1 byte before $033A) and the following routine will run: 


+, 033A 20 6F c4 JSR $C46F ;$C46F inputs a screen line into the butler. 


“. 0330 Ad Ov LbA #$00 ; ($77) is set to $0200. 

+, O33F 85 77 STA $77 S$CCOF {apute and evaluates BASIC. 

sy 0341 a9 02 LDA #502 ;$D6D2 converts the cootents of FPAcc.#1 into 
+» 0343 85 78 STA $78 a 2-byte integer, A high, ¥ low. 


+, 0345 2G 9F CC JSR SCCOF 
+, @348 20 D2 D6 JSR SvéD2 
«, 0348 20 75 E? JSR SE?75 


;$8775 prints A as a hex byte (e.g. P5}. 
;SFDS6 scart of monitor 


-, O34E 98 TYA 
+, ‘O34F 20 75 E? JSR SE775 
+, 0352 A9 OD. LDA #$0D 


+, 0354 4C 56 FD JMP $FD56 


OV3A 20 6F C4 AP OO BS 77 AD 
0342 02 85 78 20 9F Ce 20 D2 
0344 06 20 75 E7 98 20 75 E7 
0352 a9 OD 4¢ 56 FD 00 00 00 


a pee 
oe ae ae oe 


This routine is designed to print one single value only, then jump to monitor; a loop 
may be added, to print repeat values, or an RTS to return to BASIC. The routine 
works like this: 


«M 12345 
3039 


printing a single hex figure. This is the BASIC 4 version: 


.: O87A 20 E2 B4 AG OO BS 77 AD 
+: 0282 02 85 7TH 20 93 BO 20 2D 
-: QO28A C¥ 20 22 D7 98 20 24 DT 
: O292 4C BA D4 


The next routine performs conve) sions the other way, Irom hex to decimal. Again 
we can take advantage of ROM routines which already exist, und again the routines 
are relocatable, though not between different versions of BASIC. The routine includes 
a loop, so that @ series of conversions is possible; the stop key terminates the routine 
and returns to the monitor. This can be incorporated into a monitor, like the decimal- 
to-hex program. If it is, this type of keyboard transection takes place: 


.M BOON 150546 
.K 0200 512 
.N DAAZ 35982 


Thia version worka with BASIC 2; note the icop at the end, which Is always taken: 


INPUT CHARACTER {Z.G. WN FROM MONTTOR) 
INPUT HEX BYTE INTO A 


etc. 


O33A 20 &A ET JGR SETTER 
Q330 20 BA £7 VSR $E7U4 


«» 3940 AS TAY 

+, 0341 29 Ba KT JSR 92706 

~,» Q344 AA TAL 

» 9345 98 TYA 

» OF46 20 DY DC J3k $DcoA SPRINTS sMieA + X (DRCIMAL) 
+. 0349 Au OD LDA $00 

+, QO34A 20 D2 FF JSR BFFDA ;OUTPLT CHR TN ALL'R 

1. OJ4% 00 Eu SHE $0330 


Pen Pere et St ST 2 dal aaa 
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BASIC 2 and BASIC 4 monitor dumps follow: 

a: ©3394 20 EB E? 20 B6 E? Ad 20 ;BASIC 2 

ot 0342 Bb E? AA 98 20 D9 DC Ad 

+: 034A OD 20 D2 FF DU ED 

-: O27A 20 98 D7 20 63 D7 AB 20 BASIC 4 


~1 0282 63 D7 AA 98 20 63 CY AJ be 
.! 0284 OD 20 D2 FF DO ED 


SYS 829 /SYS 637 from BASIC ignores the subroutine which inputs 'N’. 


ROM routines Mathematical routines in ROM can be classified in several different 
ways. We can distinguish four main types of operation. all of which are necessary to 
a full BASIC: 

(i) Routines which perform calculations using FPAcc. #1 only, leaving the result 
in FPAce.#1, For exemple. adding .5, multiplying by 10, rounding, and evaluating 
trigonometrical functions are all operations which may be performed by ROM routines 
using only FPAcc.#1. Some of the results may be in non-standard format: INT leaves 
FPAcc.#1 holding 2 bytes equivulent to the floating-point value, 

{ii} Routines to interchange the accumulators. 

Git) Reutines to interchange floating-point uccumulator(s) with RAM variables. 
One set stores the accumulator's contents into a position in RAM determined by point 
erg; another set takes the RAM valuc, putting it into a floating-point accumulator 
before carrying out calewations on it. 

(iv) Binary operations, in which FPAcc.#1 is combined - added, subtracted, or 
whatever - either with FHAcc.#2 or other RAM contents according to pointers; or m 
which FPAcc. #2 is combined - perhaps by division or a power calculation - with a RAM 
yaiue, and the result deposited in PPAuc.#l. 

The destination of most calculations ig FPAcc.#1; it is often neccessary to store 
intermediate values, perhaps in the 19 bytes of RAM immediately below the two accum~ 
ulators which ! have already mentioned. 


ROUTINES WHICH USE ONLY FLOATING-POINT ACCUMULATOR 41. 


~---ADDRESSES-- -- ~~~-FUNCTION----* 
BASIC 1 BASIC 2 BASIC 4 
Dé6éDA DéD2 C9zD 




















FLOATING-TO-PIXED converts FPAcc. #1 inte a 2-byte 

integer in ($11} and, with the order of bytes reversed. in 

($61). On exit A holds the high byte, Y the Jow. 

ADD .§ adds } to FPAcc.#1. 

LOG, converta FPAcc. #1 into its logarithm. 

TWO'S COMPLEMENT replucee FPAcc. #1 with its 2's comp. 

MULTIPLY BY 10. 

ROUND FPACC.#1 rounds using the extra byte. 

FIND SIGN on exit, A=0 Gf EPAcc,4#1+0),1 (if ve), or 

> #FF (if -ve>, 

DB2A DB64 CD8E ABS converts FPAcc.#1 into AHS(FPAcc. #1), 

DB2D DBE7 cbDal COMPARE compares FPAcc.d! with the S-byte floating- 

point value to which A (low bytes and ¥ (high byte) point 

On exit, AO if the numbers are equal, 1 LF FPAcc. > 

memory, or #FF if FPAcc. #1 memory. 

FLOATING-TO-PIXED converts PPAcc. #1 into a 2-byte 

Integer in $61 (high) and $62 (low). Unlike DGDA/ Dé6D2/ 
C92U, the range 1s not validated. . 

DBE BBDB CE02 INT fluds INT of FPAcc. #1, leaving It In flonting-point. 

DUBB DHFS CEIF ZUROGISE puts nulls in FPAce at if theexponent ia dere. 

DEG? DEAL Dds NESATI, changes the sige of FPAcu. aL. 

DEAG DENA D1lad EXP converts FPAce,@) into @ {FPAec. aE), 

DP45 DET D229 RND entry polnt (followed by branches for tva, Zero. 

and -v¥@ arguments). 

FORCE AND RANGE ensurea random number now stored 

in FPAce.#1 wiht be within tha ranga O17. 

DFAS DFDF Dzé0 SINE computes sine of Ff Act. 61, assuming the argument 

fa measured In radlind., Note that COS leavaa pi/2 ln 
FvAce #2, and therefore TAN doen aa well, 
Fac D32¢C ARCTANQENT 


*Zaro-page addresasa apply to BANIce 2 and @; BASIC 1 hae different values, listed if 
Chapter 16 This Liat Is not intended to ba exhaustive. 






















D71E DIC COTF 
D&SBF DeFG CB20 
Dsic D853 CA7D 
DgB4 DSEE Ccis 
DAED DB27 cps. 
DAFD DBIT Cvél 


DED BOA? cDDi 


DFaB DFC2 Dzac 


= ee: 





PPLE OLOGY MOST SI A REN AE NN IE EE EY TN are anmnr ery Wenant Vente one mein ort ns ae 


| 
| 
i 
! 


2 Ie art nem one 


2 ee entre 


- » 
a efit mR rae RE en RI ARM ERE = pam ema A mm mms 


Programming the PET/CBM -367- 16; Mathemutical programming 


OTHER MATHEMATICAL ROUTINES IN ROM 


----ADDRESSES---- 
BASIC 1 BASIC 2 BASIC 4 | 
C8653 C8i3 BSF6 
cg91c C923 BSAB 
CCBS8 CC9F BDS3 





----FUNCTION---~ 










FETCH INTEGER FROM BASIC and leave its value in (311 

ADD ASCII DIGIT TO FPACC.#1. (S1F),¥ points to it. 

INPUT AND EVALUATE ANY BASIC EXPRESSION. See 

Chapter 15 on this. Note that earlier entry points enabie 

tests for string or numeric functions to be included. 

CED6 CEC8 cose OR performed between two 2@-byte integers, 

CEDS CECB co3s9 AND performed between two 2-byte integers, leaving the 
resuit in FPAcc. 41. 

c2DDp INPUT AND EVALUATE INTEGER EXPRESSION converts 
a BASIC expression which evaluates to 0-65535 into a 2- 
byte integer in $61 (high) and $62 (low). 

D285 D27A c4cg POS puts curser position on line into FPAcc. #1. 

D287" D27Cc Cc4CB STORE Y REGISTER IN FPACC.#1 in floating-point form. 

D654 D656 = CBB2 LEN. 

Ds63 D665 Ceci ASC. 

D685 DGa? CRED YAL. Each of these leaves the result in FPAcc. ml. 

0275 D733 C986 SUBTRACT replaces FPAce.#i by FPAce, #2 - FrpAcc. fl. 

See Chapter 15 for two entry points, one of which toads 

FPAcc.#2 from pointers, while the other uses current 

contents, 

ADDITION replaces FPAcc.#i by FPAcc. #2 + FPAcc.#l. 

See Chapter 15 for entry-points. 

MULTIPLICATION repiaces FPAcc.#1 by FPAcc.#1 * FP 

Acc.#2. See Chapter 15 for entry-points. 

LOAD FPACC.#2 loads the 5-byte value ta which A (low) 

and Y¥ (high) peint into FPAcc. #2. 

DIVIDE BY 10. FPAcc.#2 is overwritten by FPAcc. at. 

DIVISION replaces FPAcc.#l by FPAcc.#2 / FPAcc. #1. 

See Chapter 15 for entry points. 

LOAD FPACC.#1 from pointers A (low) and Y (high). 












DogIp DosD 










DIC DI73 c99D 


D8FD Dou CBSE 



















DS35E p998 CBC2 


DSsDOo DACA cc34 
D9E1 DAIB cc45 


DAT4 DAAE CCDs 


DAg9 DAD3 CCFD STORE FPACC.#L INTO MEMORY converts FPAcc.#1 into 
a 5-byte value stored in RAM. The position at which the 
= bytes are stored is determined by pointers; sce ch, 15. 
DACE DBOS CD32 MOVE FPACC.#2 TO FPACC.#1 overwriting FPAcc.4#l. 


ROUND FPACC.#1 AND MOVE RESULT TO FPACC.#2, 
CONVERT ASCH! STRING TO NUMERAL IN FPACC.#l. 
PRINT LINENUMBER prints 256*A + X on next line. 
(The vatue may be 0-65535). 

CONVERT FPACC.#1 INTO ASCII STRING where the 
string is put into a buffer starting at $0100, ready to be 
printed, e.g. as a linenumber, 

SQR where FPAcc.#2 holds .5 

POWER converts FPAcc.#1 into (FPAcc. #2) (FPAce.¥#1). 
SERIES EVALUATION ROUTINE. See section 16.6 on thls. 
COS puts pi/2 into FPAcc. #2; teaves cosine in ¥PFAcc. #1. 
TAN puts pi/2 into PPAcc.#2 and JIeaves tangent in FPA#L, 


DADE DB18 CDAz 
DBCS DEFF CE29 
BCOF pceb9y CFa3 
















DCAF DCE9 CF9I 














DE24 DESE DiGs 
BEF DE&8 D112 
DPOS DF 43 DIED 
D2H2 
D202 






Many ROM routines are arranged so that different entry polnts give different resuita, 
according ta the orrungement of pointers on entry. For example, SQR tonds FPAcc. #2 
with .5, then drops inte the power reudine, which automatically performs the siyurate 
Toot; differently set pointers would cnuse the funetion tye evaluate some other power, 
Tho routine at D8F9/ D930) LHSA aely pointers and performa mulliplication, taying 
lhe effect of multiplying FPAce al by log. 2. These pointers are Particularly important 
in the four major binary enleutationa of addition, subtraction, multiplication anid div- 
biun, and in those routines which Jowl dati from ASIC and store resulta back into 
HAM under BASIC contre’. 


ee a Ne rl Rm CRW meee SII MAME, OR oo 
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MATHEMATICAL TABLES IN ROM. 

---- ADDRESS 

BASIC 1 BASIC 2 BASIC 4 

CDHC = CDA3 BEAO PI 

noe noag €2b9 -32768.005 

Daal DRcy CAF? 1 
SERIES FOR LOG, counter = byte of 3. values are 
- 434255942, . 876584541, . 951800759, 2.89539007. 
FOUR OTHER VALUES: 1/SQR12), SQR(2). -.5, and 
LOG,2 = .693147181. 
10 
99999999,9, 999999999.78, and 100000K000. 
.$ 
1$ constants heid as 4-byte signed integers for use in 
string-to-numeral conversions and 1!$ calculations. 
First 9 values {fov strings) are -1G)000000, 10000008, 
~1000000, 100000,-10000,1000,-190, LO,and -1, 
Last 6 values (for Ti$} are -2160001, 216000, -36000, 
3600, -600, and 6). 


TABLE FOR EXP EVALUATION has Liloge2 followed by 
series counter = byte of 7, then values: 
.0000214987637, .09034352314, 00134226, .00961401, 
-Q55505L, .2402263, .693147186, 1. 

2 CONSTANTS FOR RND 

Il 879 546.4 is multiplied, 3,927 677 78 E-8 added. 


PL/2, 2*Pl, .25 

TALLE FOR SIN EVALUATION has series counter = 5 
followed by: -14.38139, 42.007797, -76.70517, 1.605223, 
-41.941702L, and 2*PT, 

TABLE FOR ATN EVALUATION hus series counter = 11 
followed by: -6.84793412 E-4, 4.85004216 E-3, -. 0161127618 
034209638, -.05427913928, .0724571965, -. 0899023954, 

. 120932413. -.142839808, .19999912, .33339316, and 1. 


RND SEED of .811635157 





Examples of the use of ROM routines ta perform floating- point addition, subtraction, 
multiplication, and division, Asa preliminary, to shaw how routines cin he strung 
together, try the short routine which follows, [t searches for a BASIC varinble In 
RAM, londs the value into FPAcc. 41, converts the result into on ASCII string. and 
prints the ASCH string. The effect with variable XY¥, say, Is identical 19 PRINT AY. 


9002 LDA $0300; ARTRIEZVE VARIABLE NAME FROM Tih- 760 
$0305 STA $42) ; AND STOAR IT IN ($42) 

$0307 LDA 90301 

SO030A STA $43 

$OFOC JER $CPCO;GEARCH PGA YARIABLA IN MEMORY [BANIC 2] 

SOJOP LDA 644 

$0311 LOY $465 

30313 JSA SDAAR;IOAD POLNTED-TO VALUE INTO FRACC. ¥t 

$0318 JSR $OCEG;CONVERT FPACC,#1'S CONTENTS INTO AGCIE ATAING IN $O1N0FE. 
90219 INP SCAIC; PAINT THE RESULT 


POKE 768,88: POKE 769,65: SYS 770 peints the current value of AA; locations 9300 and 


en Th a et AR BR AA bE Rm BY AEN NR HIRE aPC EEE VER SMe Sm secant et 


neh a NAL Re oe te i WR eR he 3 a nt ePID DRI Re PETE POE OP, er ri itr REI 


ee eee 


a eee eee coe rey 


Fs ee an EM at maa A UI I Aa terme 
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0301 hold the ASCII values of the variable’s name (the second of these being #00 if 
the name hus one character only). Note that some routines (e.g. DAAE£) require the 
pointers to be loaded before they are called, whereas other groups of routines may 
have their pointers in common (e.g. DCE9 then CALC) so there's no need to set the 
pointers. The version is BASIC 2; Chapter 15's list of equivalent addresses permits 
conversion tc BASIC 4 or 1. Note thet VARPTR {see Chapter 5), ii conjunction with 
this and the following routines. provides a powerful way to interact with BASIC when 
performing calculations, Alternatively pure machine-code can be used, allocating 
floating-point values their own 5 bytes of storage in RAM. tn this way, mathematical 
problems can be solved much more rapidly than BASIC permits, at the expense of the 
extra effort needed. 

The next example demonstrates addition and subtraction of two BASIC vaci- 
ables, which I've assumed have single-character names only, so the routine is kept 
short, Typical results look like this:- 


_ A™23.1245: B=32340000 
- " PORZ 768,65: POKE 769,66: SYS 770: REM ADD 
12340023.1 


Aw15: B=3. 14259265 
POKE 768,65: POKE 769,66: SYS 770: REM SUBTRACT 
6.14305265 


Only one subroutine needs to be called to change the operation from addition to sub- 
traction. AS we'll see, the routine can be converted ta multiply and divide (and per- 
form other calculations) too, This version is BASIC ¢; conversion to either ROW 1 or 
ROM 4 is no problem. 


$0302 LDA $0300; FIRST VARIABLE‘S NAME 
$0305 STA $42 
$0307 LDA #$00 ; BOTH VARIABLES HAVE #0 EERE 
$0109 STA $43 
$O03J0B JSR $CFC9; SEARCH FOR VARIABLE 'A’ 
SO3OE LDA 544 
$0310 LbY $45 
$0312 JSR SDAA: LOAD #PACC.41 WITH THE VALUE OF A (OR 0 IF NOT POUND) 
$0315 LDA 30301 
$0318 STA $42 
. $O3iA JSR $CFCG; SEARCH FOR SECOND VARIABLE, E.G, 'B* 
SO3LD LOA $44 
$O31F LoY $45 
$0321 JSR $0773; LOAD FPACC.#2, THEN ADL RESULT TO FPACC. #1 
$0324 JSR $0CE9; CONVERT FPACC.#1 INTO ASCII STRING, AND ... 
$0327 SMP S$CAIC: PRINT IT 


D773 can be replaced by D998) D778 which first leads FPAcc.#2, then enters the sub- 
routine 19 add the two accumulators, In our example this makes no difference, but we 
could perhaps make use of this by checking the value in FPAcc.#2 or in some olher 
way. 
i Subtraction can be demonatrated with the identical routine, except that D779 
Ie replaced by D733, or by the equivalent D998/D736. Again, these are BASIC 2 loe- 
ations, which must be converted to the correct values fer your ROM. 

Multiplication and division are cusy to demonstrate with the same driver pro- 
gram; typically, this sert of result will appear: 

AvSS: Be-3 

POKE 768,65; POKE 740,66: SYS 770: REM MULTIPLY A WITH B 

-168 


Aw123456: 8654421 
POKER 704,69: POXE 760,46: SY8 770: REM DIVIDE BODY A 
3. dQ0B34D2 


The BASIC 2 leertiens ta mulliply are D4 or JSR DIB then LDA SEA ISR bss7, The 
pomt ef deuding Ao wilh FRAG a exponent in to sod If the exponent iv vere, beenigse 
thun bya eeavention etach shows (had ERAce, #1 contains gre, and therefore oapyht 
wleays do ghye a peredert ot zern, Diviaion ja perfarard by DALB or by Vy then 
LOA SEF ASH DALE, Heee, the extra test inoks fue division by zere erreurs, 

2 


. 
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Example of long-precision calculation The most elegant way to implement extra pre- 
Cision in calculations (from BASIC} is to assign strings with the two values concerned, 
and return the result in a string. There is insufficient room here tu explain haw this 
can de done with all four main operations, This example multiplies two integers, with 
no toss of precision, in machine-code. A limit of 128 digits cach has been used, so the 
maximum length of the result is 256. The routine is not particularly fast. It uses the 
screen locations to store intermediate results, so the process can be watched running. 
This diagram shows how the screen is used as three buffers; the illustration has 
12345678*11246 set up. The order in which the numbers are entered affecta the timing: 
in the same way that 9897 is easier tuan 113 

gril x9897 


[ooooocoo12345678 7 ([Oooiaae Tocooago000000000 = 
ba ‘ 
$8100 + rultipler $8200 = Seltion 


The first buffer is moved one step at a time to the left, and zero inserted at the right; 
this value is added to the third buffer as many times as the second buffer indicates. 
For example, the first loop starts by adding the contents of ¢°000ff six times to $8200 
ff; when $8000(f has been moved one byte leftward (multiplying by 10}. the result is 
added four times to $8300ff, and so on. The rcutine works indepencenily of ROM; it 

is not relocatable ~ line 60 of BASIC pokes in the length of the numbers in use, and 
the very first command, 'AE 83 03', is LDX $0333, which docs not relocite; however, 
the changes required are small. Some specimen runs of this program are shown. Add- 
ition and subtraction are both easy with this type of approach. Division is more diff- 
fewlt. 


0 REM 

1 REM **4% INPUT NUMBERS AS STRINGS *4ax 

2 REM 

10 INPUT " FIRST NUMBAR*; NLS 

20 INPUT "SECOND NUMBER"; N2$ 

30 IF LEN(N2$) < LEN(NIS) THEN N2$="O"4N2$: COTO 30. 

40 IF LEN(NIG) < LEN(N2S) THEN W1$e"O"+NIS: GOTO 40 

50 N = LEN{NIS} 

60 POKE 899,N—L: POKE 9L1,24N-1: POKE 952,2#*N-1 

99 REX 

100 REM *4** POKE IN ZEROS AND INITIALISE *ae& 

101 REM 

110 FOR L = 32763 TO 32768+ 2*N-1: POKE L,O: N&XT 

120 FOR L = 33024 To 33024 + = N-1: POKE L,O: NEXT 

130 FOR £ = 33280 TO 33280 +#2*%-1: POKE Lith: NEXT 

199 REM 

200 REM #4**® POKE IN VALUES *#4* 

20% REM 

ZLO FOR La}27A8+N TO 32768 + 2a-1; POKE L, VALCMLBS(NIS,L-32768-N+l,1)): NEAT 
220 FOR L=33024-TO JIU24+NwL: POKE L,VAL(MIDS(NZ§ ,L-3302471 ,i)): NEXT 


23) s¥S 900 

299 REM 

300 REM ***e PEEK AND PRINT RESULT wAAR 

30 REM 

310 FOR L = 33260 TO 332804 24N-Lt V5=STRS(PEEX(L)): VS=RICHTS (V$,1) 
320 LF ¥$<>"0" THEN Fel ‘ 

330 LF Fel THEN PRINTYVS; 

340 NEAT 


FERST AUMBRR FY LUPEVLVIEDTL YS 
: O84 aE 83 O03 BP WW) BE RM} ta 
> OFC AA 1B AD OF BY Of BD 79 SECOND NUMBER 7 99999999999 
+ 0394 OB? C9 0A SO WT NS £9 
: Ose OA 99 OU AZ BR OIA ED oA 
ot O§FAS DO ES CF #109 40 TF A2 
et UJAC OF AG OT NY 0 BD 9p 00 
»t O3M4 J ha Ca KO WP fd) Fa AD 
e} O3aC UD 9 OO HO FO C2 60 FE 


LOAD ALIPAY SP SSAA LAG LASS 
FURST NUMEZR 7 9155599935599 92595 959559 
SECOND NEMMEM PD PPPPTAP TREE ET? 


SVZNIGIGS 4 S298 L495 FERN ABA EP Pat 2 456 7901294 


EAGER EO PL A ON EY FEA I OA So RI Sh RRO Amine tT 


20m eh ec tite ee At Se A mace rt ell OR ar om i 
ie 
a 


te a: le lm A re. 


ae RN CD ee a 5 Re eee ee 
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The series calculation routine Mathematical functions are not evaluated by a table 
lookup nmiethod, but by ecaiculating a fixed number of terms of a series; the length of 
the series depends on tts speed of convergence. We shall sec in this subsection how 
the process works and how to write functions which can use the evaluation routine. 
Firstly, let's sce where it is in ROM: in fact there are two routines, one of which is 
called as a subroutine of the other, and which is only once called to evaluate 4 series 
(oy EXP). Most routines call the more complex first routine. The locations are: 


BASIC 1: DEF3 (main routine) & DFOS (subroutine). Pointer is ($CQ}. 
BASIC 2: DF2D (main routine) &@ DF43 (subroutine). Pointer is ($6E). 
BASIC 4: DID? (main routine) & DIED (subroutine). Pointer is ($6E). 


In fact, the first routine is largcly concerned with housekeeping, i.e. making sure 
that the numerous values which are stored do not get overwritten. The second routine 
performs all the calculations. To use it, load the pointer with the starting byte of the 
series. For example, DE72/DEAC/D156, depending on ROM, holds a table of cipht 
floating-point yalues preceded by a singte '7'. The single byte is a counter, which the 
evaluation routine uses to count its multiplications. Slightly confusingly, it uses a total 
of one more constant than appears in the byte - 8 in the present example - where the 
final vatue is simply added to the cumulative total. Let's take a concrete example, with 
BASIC 4 this time: 


LDA #$56 

STA $6E 

LDA #301 

STA $6F ; POINTER ($6E) NOW POINTS TO $0156, 1.E. '7* THEN 8 NUMEAALS 
JWP FIED; EVALUATE SERIES AND LEAVE RESULT TN FPACC. #1 


After this routine, FPAcc. #1 holds 


1+ 699..." 4 .24.. 47 + .0555...07 + 0.2. + .000022...x7 


where x = the starting value in FPAcc.#i. The coefficients are taken from the table 
for EXP evaluation, several pages before this one. Note that they appear in reverse 
order, because a recurrence relation like this has been used: 


Rosult = CCC. C(Value, 


USR provides an easy way to observe the results we can get so fur, because it puts 
the argument into floating-point accumulator #1, jumps to our routine, then prints the 
value now in FPAcc.#l if we have USR(X), say. We find, on POKEing locations Lend 2 
go that they point to the short routine above, that if X is in the runge 0-1, PRINT 
USR(X) is ahnost exactly 2%; outside this range the approximation progressively 
worsens. This is how CBM BASIC calcuintes functions. Of course, funetions genirally 
aren't restricted so that their arguments uppeac only in & smatl range tike 0-1; 4 
transformation is used with some values, and not others, to put any value inta a forn 
In which systematic errors are minimised, For example, SIN not only takes the remain- 
der after dividing by 2pi, but alsc subtracts the result from #4, depending on the 
sign, so that the powers of x converge more rapidly. 

We cun write our own series, and calculate our own Functions in machine-code, 
using this routine, For exemple, POKE 1,122: POKE 2,2 [l.e. $O27A] and 


*x + Value,)*a + Value,) # x + Value, wee Value. 


$027A LDA #$00 © with $0300 1 ;DECIMAL VALUE 
#027C STA $68 90301 12 
$027 LDA #$03 $0302 0 
$0283 STA SHF $0303 0 ;e4 IN FLOATING-POINT FORMAT 
$9262 SMP $D1ED; BASIC 4 $0304 0 
$0108 0 
soj0a oO 
$0307 0 . 
$0308 4 80 IN FLOATING-POINT FORMAT 
goog 4 
$030A 0 


is an ensy example, PRIST GikCX) giving Gg - §X. For instanee PHINT Usite1d) 
prints 5, PRINT USRE4d. 7) printy 22,95. (The firat byte In tha table cannot iar 0; af 
lt Is, 256 temas will be evaluated, whieh is probally not the intention). Tou maaan 
power of x uquals (he ningbe: byte at the start of the ingle, aa if ed provictess Oven ai} 
accuracy, a Mingla byte af S must start a table of 4 valucn, making FL bytes in all. 


. 
“ 
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It may be worthwhile writing a series routine for functions which are often used in 
some Apecialised Field; the resulting coleulations will be faster than a BASIC function 
definition. The point ubout Microsoft's method is that it does mo? simply employ an in- 
finite series which has been truncated: instead, the maximum error within A defined 
runge is kept low by finding an expression of best fit according to least squares ert- 
terin, Taking sine (x) as an exampic, this can be expressed as a ecries: 


2 
x - Xx axSe xe... 


a br Tr 


ae een a aaa range, we can always improve on the truncated series; thus 
is between 0 and pi/2 only, and we want an approximation : in 
terns, this series: . nt coer ranieaee 


L.Olx ~ ,O424x? - .126x? is better than x - x3/6 i R i 
error of about .(02 as against .08. ae al 


A fairly routine method to valculate such series approximations is presented here: the 
interested reader should read further in Chebyshev and Legendre polynomials et ‘al 
The chief problem is that the accuracy is limited to that of the CBM, assuming that 
machine does the calculations; this means it is impossible to get results precise down 
to the last bit. In view of this difficulty. [ have selected un easy method rather than 
one giving the best possible results. The object is to minimise the sum of squares of 
differences between the function and its series approximation over some range select- 
ed in a way that enables any (valid) argument to be processed by the series. To 
minimise over a range. we minimise an integral. As an illustration, we'll take a general 
function f(x) and approximate it by @ + bx * cx?}over the range x = Gto x = 1 ‘This 
shows the method, with the minimum of urithmetic. ; ; 

Bk each value of x, the error = atbx+cx?-f(x), 

the sum of squares of errors in the ran 0 is gi : 
fhearoxeex?-f(x})! Hh ge 0 to 1 is given by: 


To minimise the entire expression we integrate the partial differentials with respect to 
a,6, and ¢; this gives three equations, since there are three unknowns:- 


5} (asvxsext-f(x)) ax = 0, 
J gx (arbxtext-t(x)) dx = G, 
and f Ext (evbxsext-£(x) dx = 0. 
The expressions in x are ensy to integrate; the expressions in f(x) may be integruble 


analytically, or a rule such as Simpson's cun be used which will i 
f 8s Sim : robably be quick 
and easy, The intermediate result is these equations: ‘ ages 


a b i 
UF o pet + Set) - 19 tends © 0, 


a b eg lh i 
tee tte glo - i wf (x)dx = 0, 
a,b €5,1 71 

and (3° ral + ror ~4 0 xif(x}dx = 0. 


And these can be simplified into this final form: 
afte b/zs cz = Sd tiara, 
a/2+ b/d + c/a fh xeieddx, * 

and a/3 4 b/t + c/5 © Sh xt e(xyar. 


There equations cnn be dotved using our matrix Giversian progrun, sad estimates of 
6,b, and ¢ found. The matrix i4 aot ideal from the computational paint af view, Wut 
we needn't worry leo much about that. Note that the matriy has different element if 
the limits are not U to ft, and the jimits of the Inteyinin of courae differ too, i 

Let's finish with a xhort example: what ja the beat approximation ta e* in the 
form(a * bx} where x varios from 9 to 1 only? The solution: for a and b comes from: 


a + b/2 el elds wats ele o-t, 
and a/as b/d =f7 xe "de 9 {xo%-0%}f at, 


Which gives e+ ,873 + 1.690x In the required range, 


TP are ae ser eee : rot 
a 2 tere, ors sey 
oad tsa ene mene Ra ee ek ee ena? 
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CHAPTER 17: PROGRAMMING FOR BUSINESS AND EDUCATION 











17.4 Business programming. 
17.1.1 Types of systems 

if predictions of miilions of computers in the Engtish-speaking world ore true. 

then the present situation is not even a drop in the ocean" (PL) 

At the time of writing there are reported to be about 100,000 microcomputer systems 
in the U.K., of which a substantial proportion are Commodore machines. About 24 of 
users are in user groups. The general level of expertise is not very high; considering 
the complexity of these machines, this is, of course, not surprising. Most CBM hard- 
ware is distributed through official CBM dealers, and the presence of such dealers 
helped Commodore to achieve its leading market position. Software is a rather differ- 
ent matter. Most microvomputer manufacturers want to make and sell hardware, which 
is in any case logically prior to software: sources of software are far more diffuse 
and verious, and may not come into existence for years after the introduction of a 
machine, 90 there is no guarantee thut software which is perfectly feasible technically 
wil actually exist. There gre broadly four microcomputer markets: business, science, 
education, and personal computing (‘home' computing is sometimes distinguished from 
‘personal’ computing). in the U.K., the home computing market is small, because of 
the cost of the machines; or at least this was the case until Ctive Sinclair introduced 
his ZX-80 and -@1, On the other hund, this market sector is probably much targer 
than appears from the figures, because many machines bought for ‘business’, for tax 
reasons, must effectively be used personally. Estimating the proportion of machines in 
serious use is difficult; my own impression is thet many microcomputers in ‘education’ 
are very much underutilised, and that s significant proportion of business machines 
fall into disuse after a fairly short time. Whether failures are principally a hardware 
matter or caused by software remains a further unclear erea. However, it is at least 
clear that expericnced hardware support and after-sales service are likely to be nec- 
essary to a successful system. 

As regards software, the most widely-used business systems appear to be those 
which use data which is not crucial in day-to-day running of a business: mailing lists, 
price ists, in-house telephone directories, address book systems, quarterly requests 
for fees, illustrate the type of thing. Sales and purchase ledgers, order processing, 
and payroll, although potentialty almost universal, seem more resistant to micro-comp~ 
uterigaticn, From the buyer's viewpoint, systems are very hard to assess. as we shall 
see, $0 caution is understandable. The situation is net particularly easy for the pro- 
grammer and/or anatyst either, a good system may be expensive to produce, perhaps 
prohibitively so, end a user may not appreciate the problems which may occur with 
relatively Insecure systema. A packuge may be copied or bootlegged; a client may 
request impossible thingy: 8 specification may be changed at the lest moment. The 
sections which follow wili, ! hope, cast some light on these Issues, without necessarily 
offering definite selutions. 


17.1,2 One-off (‘bespoke’) systems 

Tif be nice to hav? a machine that daes exactly what f want" fAnon) 

Most one-off systems rely on previous programming work; tn an cxtreme case, only & 
cllant's name or company need be changed throughout 4 set of programs. Normally, 
stindird routines or metheds can ov toed. Consequently, auch systems can legitinvate - 
ly vary cnarmousty in prkte. Another qource of variation is the crror-trapping and 
validation of the programy. This ought te be lafarnd to mateh the lovel of skiL of the 
waery, Pounmotivated staff are golny fo be expected to key in large amounts of cata, 
property validated jeput, the use of menus, and comprehensive Instructions have ta be 
provided, olherwise Sheu wil inevilably tu: errocs. Et any case, KOmG form of auctit 
trail or revard on paper must be printed In case of lous of data, ff {t can be arranged 
automutie fie packup is desirshie, since the usera may not understand Lhe Imporlinee 
of cupies af datn. Mush of thie is far Jess tapartant In thi cage of preyrams at Une 
kort deveribect ba the dast section, whieh (fur eaample) sean an wedetrenss Tile ley nei: 
ero aceupation, or perform sume set idan revenue esleulstion, Normally, thar eadenury 
indo whieh a program fells is fairly ubwieus ta a programinscr of rven moderate exper 
fenee: it ia usmdly clear whethur or Hut a proposed sy ale ly too large ae ilkely ta 
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overstretch the hardware, Sometimes it is impossible to be sure, so a preliminary 
trial may be needed, For example, is it possible to write a system which can plan the 
routing of film cameras and other news equipment by air to several! cities (say. yome 
capitals in Europe) in an efficient way? 

When computerisation is considered, a client may not appreciate the importance 
of a clear specification of a system's function; in particular, the fact that although 
almost any system con in principle be programmed, a cost-effective approach may 
require the drawing of more-or-less artificial boundaries. For example, mailing-lists 
have ‘dead wood' procedures, which remove names after (perhaps) a certain number 
of nun-responses, but respondents must be categorised in a common-sense way, en- 
suring that Category ‘A' are not removed until 4 larger number of mailings than 
Category 'H'. The fineness of the categorisation can be decided on the basis of ex- 
perience. 

As an illustration of requirements which cilents may request of software houses. 
fet's consider the following typical! list (modified from an articte by P Crozier in Com- 
puter Weekly, Jan.'#6): (1) The software should be modifiabie by the unskilled lay- 
man himself whenever his requirements change: (2) The system should be as foolproof 
as possible. For example, it should be impossible for programs to be run in the wrong 
order, and there should be no chance of data being lost through fack of backup cop- 
jes. (3) The system should be simple to operate. A single rule should centrol the 
operation of the entire system. (4) The system should be a ‘fully integrated business 
system’. (5) Other applications programs should work with the system, even when 
they are written by other organisations or individuals. (6) Reports (i.e. printouts of 
significant aspects of the data as it is currently stored) should be obtainable ut any 
time. (7} Help must be available - ‘within one hour's drive' is the criterion suggested. 
(8) Take account of ongoing costs, not just purchase price. How realistic is a list of 
this sort? In the case of most microcomputers, we can immediately supplement it with 
the requirement that a validulion program of some sort should be available which can 


method, Without this, a suspicion thal the floppy disks muy hold ’bad' data may be 
always present. The use of passwords ta access the system is also sometimes thought 
to be desiruble. Most of the list's desiderata are difficult to achieve, and are much 
More restrictive and stringent than most miinframe systems apply. Let's look at the 
eight points in turn; 

(1) Software modifications. 


‘ Programs which are paramieterised, or which keep 
current parameters on file, are casily modified by users: for example, a set of percent 
increases applicable to a number of classes of items can be soft-coded so that the user 
has the option of altering them. Similarly, titles, headings, and printed comments in 
general may be programmed in a way enabling them to be changed. Apart from theze 
rather elementacy examples, things are less straightforward. Programmers may not 
want their programs to be accessible to the users; this depends on the commercial 
relationship between the software supplicr and user, There is a further problem of 
determining responsibility in cases of failure of a modified system. 

{2} Foolproofing. There is no way to make a system completely foolproof; the 
attempt may even be counterproductive, if an elaborate act of checks gives the users 
too much confidence in a system's ability to recover from mistakes. The single most 
valuable insurance aguinst error is a competent user to whom the buekup procedure, 
the operating procedures, and the function of Indivicual programs hus been explained, 

(3) Simplicity. it Ig a mistuke tu aysume that the shortest commands are the 
most efficient, f.c. that the number of keystrokes ts Inversely related to efficiency. 
Single-key triggering of important system functions can be disastrous. This of course 
Is the reuson for queries like ‘Are you sure?’ in HASIC 4. A uniform set of data ontry 
ennventiona Is impertunt dn any system. These should ineurporste the normal validation 
features, but muat also moke provision for tie correction of vropc entering, by far 
example) redisplaylng the cententa af a record before it ds filed, anid allowbiy any of 
Jia fields to be culled by number to be corrneted, See seetion 17.1.4 for more on tin 
subject. 

(4) Full Integrated system, The point here - which ls probably more relevent 
lo packages - ‘i ‘that all party of a syntem should ideally be developed ag the result 
of an overall analyais, and net assembled daa pleersent fushlate whieh msy Cute un: 
expoctad fullures if the subprograms un nut fb tugether correctly. Fram the palnat af 
view of a huyur, there Is no way of knowing whether or not a ayatem in Integrated’ 
In thls aenne, so there seems Title point In laying alresa on this, 





verify that the stornd data has not heen corrupted. Hashtots! techniques provide one 
§ 
{ 
! 
H 
| 
i 
{ 
{ 
c 


ST. AS, SARA Ai cma Sk 24S AO Uhm ARE SSS ET ERR EY Mn re eee eo me” 


ee ee en ene | 


Programming the PET/CBM -475- Business and educetion 


(5) Compatibility with other programs, Every system relics upon its files having 
a structure which may well be unique te the program. [t iy impossible ta ensure that 
any system wiit be genera//y compatible with all other software. Ta a limited extent, 
however, this is possible; a number of packaged software products are able to use 
each others’ files, notably in word processing packages where the file structure is 
often a relatively simple dump of consecutive ASCII strings. 

(6) Immediate availability of reports, This of course is correct. Easily available 
reports are valuable not only becnuse of their immediate usefulness but also as a 
check on the working of a system. However, there may be some problems with reports 
im which vatues are reset. A program to provide end-of-period summaries, which reset 
totals to zero in preparation for the next period, cannot be run at any time, so it 
may be necessary to separate the reporting part of a program from the resetting part. 

(7) Availability of experienced help. In any sericus system, this is vital. it is 
not very easy to ensure continuity over time. Software people may be reluctant to 
provide continual after-sales service, which might be perceived as @ drain on the 
resources of the company. There is a further problem that a system may change over 
a@ period, so that there may be no software person familiar with some version of @ 
program, although this is usually a problem only with packages. Moreover, a company 
may have so many different systems written that keeping track of them all is very 
difficult. In practice, therefore, even ‘experienced’ help may be less useful than the 
owner of & system hopes. Some software houses offer no maintenance whatsoever. 

(8) Costs. Although it seems obvious that the costs should allow for the poss-~ 
bility thet changes in programs will be wanted, userg generally have no way of est- 
. imating the extent of such enhancements or their costs, which may be large. One way 
around this is the fixed-price or ‘turnkey’ system, See section 17.1.9 for comments 

on the advantages and drawbacks of such scnemes. 








17.1,3 Packages 

"Standard software packages are untikely to be foulty” (Dept. of Industry guide) 

“Don't ever buy a system without sscing it demonstrated. The reason? 

There's so much under development. The good ones are pleased to 

demonstrate it. The others ... welf ,.." {MA} 
From a programming point of view, packaged systems are not very different from one- 
off systema. The main differences are (i) the target market must be fairly well under- 
stood, and (ii) proulems of copying and Lootlegring may arise. Section L7.1,10 looks 
at this second point, Very often the first is taken care of by one of the partners in 
the software-producing venture: accounting. medical, legal, and games packages have 
been produced with the co-operation of people with expertise In these fields. The 
intention is of course to sell a relatively large mumber of standardised program pro- 
ducts at a price lower than would be possible with a once-only program. All purehas- 
ers can be offered similar serviee terms, and possibly regulur updates to their pro- 
grams should bugs be found or (for example) government rules changed. This is 
however not a3 ensy oa it appears at first sight. Hf all users want a product which 
has been thoroughly tested (received its baptism of fire...') by other users, it Is 
Gifficult to see who Is to undertake the initia! testing. And 48 o product improves, its 
qualitites make it automatically a candidate for copying. Copyproofing is not casy: It 
is possible that Commodore may offer help in this, but they may not, 

it might appear that purchasera have an easy time, but this is not really the 
ense, For reasons divecussed in 17.3.5, reviews of packages are not likely ta be of 
much value. Users aay be offered old versions of packages, and be completely un- 
able to find out hew up-to-date js the version belng sold them, The exceptions are 
widely sold packages, such ag the -Cate range ef programa whieh started with Vint- 
Cale (1M), the characteristios of which are well Known. Word- processing packages ire 
aiso widely Known rear anderstusd: Wordgre CUM) and Worderatt CLM) ilbiatrate the 
type of thing obtainsble at prevent. A Goer should however sill test such products, 
if he is eancerned to wetradby use chem, He omoy find dhat the faciiities for riune and 
nédress Insertion In fetters are inadequate, ar that his printer is net catered for, or 
that his apeentorn eonnet use it, Alda, of course, stany given time there is om Catate 
of Due gre te whinh most packages confer and which ny not have been pusted la 
ahhh level uf developmeat, tur exainple, da word prromedwor packayes so farias 1am 
aware offer propartionai vpariag, even thougi: medeen dalyywheel printecs are rqulp- 
Peel to dinndle this, or welereeconpouter vyite . Avtontie hypheration, teing a Hieary 
Of prefpeen nod suffixes lo disert bredks la words Csamedines unsuccessfully: pro mpl 
ata sven to be nen exivtent, although tf is teehaivelly feasible. 
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17.1.4 Input/Output. 

"ft can take years to key in dota...*% (MH) 

We've seen (Chapter 4) some examples of 'input' statements which use ‘GET‘ to give 
fult control over a system's input. The object of this is ta avoid INPUT, which has 
many features making {t unsuitable for serious applications, such as rejecting conmas, 
nat distinguishing between shift-space and unshifted space, and allowing unwanted 
cursar-contrel movements to take place. Systems designed for use by typists may 
need special validation, far example to ensure thet the figure ‘1’ is not entered as 
lower-case ‘L'. The most thorough utility provided by Commodore is the 'Standard 
User Data Entry Environment’, published as assembler soutce-code in CPUCN, Vol. 3, 
Issue 3. in an article by Paul Higginbottom. BASIC 2 and 4 versions are printed in 
the same article. The routine is too long for description here, but basically is stored 
in high RAM where it inputs strings into a predimensioned string array. The position 
of the fields is not determined by numerical parameters: instead the screen is scanned 
for delimiters, which the published version takes to be '<' and '>' to mark the start 
and end positions respectively. Since it is scanned from $8090 upwards, the fields are 
automatically input in consecutive order. This is the 'Data Entry Editor’; it is only a 
part of the 'Environment' which Commodore say in the article thut all software must 
roughly conform to in order to receive ‘Commodore approval'. Readers may therefore 
be interested in the following brief summary of the standards: 

(1) A title on the top line(s) should describe the current program. The bottom 
lise should be reserved for error messages or prompts (‘Enter YFS if data OK"), and 
perhaps messages (‘Please wait while search continues’). 

{2) 'C' should continue from one sereen to the next; shift-return should be the 
code to uccept an entire screen of information. [! do not personally believe that the 
use of shift-return in this manner is sensible, because typists don't usually accept 
a distinction between shifted and unshifted carriage return}. 

(3) [CLR] should return every field to its initial value. [HOME] should move 
the cursor to the first field. [UP] and [DOWN] should peruit movement between fields. 
[INSERT], [DELETE], [LEFT], and {RIGHT] should allow editing of each field. This 
condition Is likely to prove more difficult to program than any other feature. [RET~- 
URN] validates its field and moves the cursor to the next ficld if the field was ant 
detectably invalid. [STOP] should provide e# ‘help’ favility (i.e. a display of instruc~ 
tions. or - this may be more difficult - a return te the main menu). 

A s¢reen can enter ‘sereen accept/rcject mode’ when a final [RETORN] or 
cursor down teaves the last field of the screen, or when [SHJF1T-KETURN]J is pressed 
at any time. In this mode, cursorup, [HOME] or [CLR] are to act as rejections, and 
shift-return as accept, So two consecutive shift-returns at any sisge accept date. 
(Personally, I prefer a more meaningful “YES’ or 'NO'], 





A data entry method which iv used on large computers is the keying-in of 
identical! duta by two different punchpersons, euch set of data being separateiy stored 
on fite, und compared by the computer. Discrepancies can then be corrected, The 
Idea ig that neither person keying in data bothers to correct anythiny, In the case of 
anal! aachines, there muy not be siorage spuce to filo duplicate data, or time to enter 
the data twice, so such methods are probably unsuitable. 

While numerle data is standard in format, alphubetic data ian't, and it may be 
worthwhile to decid: on xtandacds go that repurts ete. are uniform in appearance, Sec 
the examples below, one extracted froma list of standards, the other showing a report 
Incorporating them. 


A {Anps] 

C (Centigrade) [Capaclrance) 

Cd (Cadmi um} 

Tix (Hortz = frequency) 

L iLicera] 

RL [Nlekol] 

NEO 1 17% Outer versal Ls] aA 2.54 510,89 
Met <oAe TO 194) Candancer | 6 ot 7.70 Data, BAF 
wera), 2 SP Ver) Stopasr & SL ett oan oF 
NA E=@l ue 3 DONG Preereten | iatetey ic Mit 114, 9% 
Li heath ata Ly ee | 1D fyernta citi Ay nh t 14a yaa 
HYD \ S tio Stand vend iaeubater  H L 3149 44, of 
CH= PA Z Id Flee Stam] tlvan Zi anatar A Parad ata tl 
atin Paget i} Wd Pde tard owed be dep he b $4, t0 and Gel 
wi sfAe V4 4 ft Rak A 1 44 fri tet 
OVE dae 6 2 Clipa i L 3,44 FIL, 
Nd edalesine ot Lote ytng Matlawt, 220-2 ae¥ ac F n W74074 12a, 34 
Ovi SIN tu, VP Ttveer mn cect | eat ae t Woy Ayeeatet 
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Hardcopy of input data may be produced as the data is input, providing a 
record of 4 series of transactions: see the example below, which records two trans- 


actions only, 


8/ 3/81 


BALM PESCHIPTION OF ATCA = COST PRICE PELE. CRUSS-REF LACH, 


CEL-729-700 V3 Mew Stack Leerl: eTasual 15. Thermistars neu 
CEL-725-1100 (1) dew Shack Level? stesue: 4b. Indection Poet feals att 
EwD OF BOOK STOCK ITM ENTRY FOR 8/ 5/81 


17.1.5 Testing systems 
Wome of the faults fin puckages] were quite incredible" (RW) 

The quotation above came from a manager of a micrucomputer department of a retail 
chain, whose policy was to stock only thoroughly tried and tested products. They 
employed external consultants ta report on the good and bad points of software pack- 
ages. They found plenty of eech, but the relevant fact as far as this section is con- 
_cerned is that the process was expensive, equivalent to about a year's salary per 
package. This is the reason for the fact (mentioned before) that reviews of packages, 
where they exist, are very likely to be superficial, and are often little more than 
quytations from handouts end press-releases on systems, It is also the reason that 
many users wait until @ solid base of users is established before buying a package. 
From the programmer's point of view, bugs are nat necessarily undesirable, since a 
client's independence is undermined to some extent if errors appear in his system, 
Moreover, 4 perfect program is a program eminentiy suitable for copying and piracy. 
Most mainframe packages are continually modified and upgraded. often with regular 
monthly update sheets circulated to registered users, cithough one hesitates to 
describe this as deliberate policy. With the computer industry at its present state of 
evolution, it is difficult to be dogmatic in this area. 


17.1.6 Users and programmers 
“'This guy rong ond scid his computer wasn't working. He'd typed in 

‘What is my birthday?! and it hadn't told him* {LS} 

The following short notes are intended te instruct, and warn, of potential hazards in 
the micrucoriputer arena caused by people rather than machines. 

{1) Salesmen. Many microcomputer salesmen don't really know muvh about their 
machines, and perhaps can hardly be expected to. Advice from the technleully comp- 
etent will often be better. 

(2) Typists. A computer like a CAM has a keyboard and is therefore automat~ 
iealty categorised by many office workers as o typist's thing, There are however a 
number of differences in style between typing and data input (for example, with 
regard to error correction} which may make the stereotype inappropriate. In aridition, 
don't assume that someone can alt in front of a sereen for cight hours a day: this 
muy be too much, Four may be batter. , 

(3) Users’, A ‘user’ can be defined ny semoune wilh immediate responsthility 
for no system, TH may prove impowibie to expiain such concepts us disk copying, the 
fens for thdiness nod dennliness, of the way no system works. 

(4) Departments. Inter departmental rivalries aod differences in ottituce inay 
cause problems in easy orgendcotivas other than the very smatfest, Errors or cadssions 
which ore well Known daoone department may never be formally meatlonedd to the 
people whe ere warklng with the Tle rpeompuater 

to) Computer derertmenty, Bly argantatioas’ compuler depurtircnts auiy teas 
detvely oppor Ladiicrocenpulers, partly far tie yood reason Chat they unas sea 
wrong, (Thin ia why macros are often deaeribed jos Jenteutiator with video dit play? or 
Insert vueh fers wher the departaent 4s budyet requedis are subsiltledi. Phere may 
beg fener af ‘dlutritated pranecuag', of the rnmuigers vay kono} robbie of gage reas, 

It is oulse quite commen for muarfrane: people to be ueable to appreciate tae Lanita totes 
wfoalerueamputers, whieh msevitebly lack amet big inachine features, 
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Programming the PET/C&M 
(6) Programmers. Some readers may be interested in the general perception 
of programmers and anslysts within the computer industry. Computing has evolved 
with little in the way of formal training and qualifications, so assessment of would-be 
computer personnel is fairly difficult. One hears of people describing themselves as 
‘very experienced programmer’ who turn out to have two weeks' experience an & 
machine. The first belief is that analysts are extraverts aud programmers introverts. 
This ig at least a clear-cut theory, something which can herdly be said of the assort- 
ment of theories on programmers. I've heard it suggested that programming ability 
goes with neatness in form-filling, with the capacity to use jargon, with interest in 
chess and/or bridge. and with the desire to feel control over the machine, Disabled 
people have been recommended as potentixl programmers. Pecple who are good at 1.Q, 
tests are likely to be a good bet (1 imagine}, since the pencil-and-paper nature of 
the work and its emphasis on formal logic resembles the tests quite closely, Yet anoth~ 
er belief is that programming skill can be expected to correlate with fluency In 
English. 





47.1.7 Documentation 

“Make sure you've gat paper, paper at} the way" {ME} 

There is a British Standard on documentation: BS5515:1975 is the Code of practice 
for Documentation of Computer-based systema, This is exhaustive, but too compre- 
hensive for microcomputer systems, instead a smatl subset taken from the code of 
practice will probably serve most purposes, perhaps slong these lines: 

(1) Operator's Manual, This might include the procedures for switching on and 
off, and for handling disks, loading paper, loading programs, and so on. It should 
include an explanation of input conventions fc.g. as deseribed in section 17.1.4), and 
also of error messnges, even if these are supposed to be self-explanatory. [f there 
are conventicns to be followed when inputting data (as in 17.1.4) these should be 
listed, and a troubleshooting section of a reasonably clementary kind wiil help avoid 
panics caused by the printer running aut of paper and problems of that sort. 

(2) User Manual. This is intended to explain the system, without going to the 
tengths of inaluding program listings and other technical documents. ft could include 
an explanation of the file structure, a chart of the processing sequences of the pro- 
grams, an explanation of the backup procedures to be adopted and the validation 
techniques to cheek for successful running, and a hardware section Jisting the 
suppliers with details of purchase dates, faintenance contracts, contact names, and 
go on, 

(3) System manual, This should provide a comptete reference to the working 
of a system. Typically a specification will Le included, and a detailed breakdown of 
the file structures used, with fietd types, field lengths and so on. lf the system Is 
partly in BASIC, listings, subrouline maps by Hnenumber, vurjable tables, and 
details of wedges und IRQ alterations must be listed. Memory-maps of machine-code 
and annotated machine-code listings ore needed. Finally, a log of updates and their 
(intended) effects should be kept. 





17.1.8 Security, 

Sufficient security can usually be got by simply locking up the machine, perhaps 
taking home important disks ur keeping them locked in lackable diskette cases, Backup 
copies of data should be kept separately, though. Some microcomputers are portable 
enough to be curried away; the PET/CHM range are on the heavy side for thls. It 
la not unknown fur vhips to be taken out, however, Some uners mty like to ensure 
that no dinka are taken inte their computer room or taken out, Pusswords may be 
useful If several groups of users run programy on the same machines, but these are 
likely to be vulnerable to compatent programmers ant are effective only with so-called 
‘alve users’. Complete duplicate systema are often fensible and may be worthwhile. 


17.1.9 Contracts 

A software house typically haw a contract with ita clients along these lines: 
Por a flacd price, a onystea apeelfication und programy will be produced! fa Cay} 
twolve weeks, ‘with no litbitlty Cor variation’, After (he ayaien specification haw been 
agreed with the cHent, work gue ahead: tha cllent Ja expected to supply Ueit dota, 
and on delivery of the system the results produced by the system usu the test date 
are supplied te the client, whe la expected to eheck whether the ceaulis accord with 
tho apectfienth . After an iulerval (perhapy four weeks) the prograasa ara deemed to 
accord with t) specification. 
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There may be penalty clauses if delivery is late; occasionally stories circulate 
of freelance programmers sued for malpractice, But gencrally something like the 
scheme above is adopted. It is in fact rather unfair on the purchaser; he may have 
to wait much longer than he thought, and be asked to supply test data without any 
real appreciation of how to do this - for instance, it may not occur to him to supply 
data with deliberate mistakes to check that the system rejects them. Also he may be 
asked to approve & specification with only a vague idea of what the resulting system 
will appear like in practice. Finally, the lapse of time allowed to detect Gugs may be 
insufficient, some programa never being run. 


17.1.10 Copying and ‘piracy’ 

We can distinguish copying, where a friend or acquaintance copies a program 
for his own use, from ‘piracy’ or ‘bootlegging’, in which the copied program is not 
only copied but also sold. The cassette games market is said to have been killed by 
copying, some companies no longer bothering to sell them because copies quickly cause 
a severe drop in sales. Cassettes can of course be copied by audio methods, so that 
any software protection is simply bypassed. Disk programs are much more copyproof- 
able, but the methods are not widely known. In any case, it may only be @ matter of 
time before programs to copy ‘uncopyable’ disks start to appear: this happened in 
1981 to Apple, whose disk operating system is in RAM and more accessible than 
CBM‘s to disassembly. There are other, more subtle forms of copying too. 1 met an 
enthusiast at an exhibition who told me that he'd written a trade estimation program, 
which had reappeared, in improved form, but using exactly his methodology, as 4 

. eommercial system. Beyond remarking on this problem, which is also endemic in the 
recorded musie field, it is hard to suggest any solutions." One suggestion is that 
users might be willing to pay for a newsletter of updates. or that an elaborate 
manual fora system might be easier to spot as a copy than a disk; and that a system 
might include spurious routines that perform no useful purpose, but can be looked 
for in @ suspected pirate copy. Hut even if a pirate copy is certainly identified, legal 
action may hardly be worthwhile. 





17.2 Programming in education. 
“They work in an orderly way for hours. The attention-getting cepacity 
fof microcomputers} is remarkable" (DL) 


17.2.1 Costs 

___ Microcomputer costs have continued to drop; VIC is Commodore's low-price 
machine which is intended to compete in the cheap home and education markets, The 
apparent costs have dropped more rapidly than actual costs: when allowance is made 
for external TVs, cassette recorders. RAM packs (more expensive than RAM chips!). 
and other equipment, particularily diska and printers, much of the apparent saving of 
‘echeap' systema may disappear. In the U.K, it is official policy to support, or at least 
lean towards, British products; education authorities for example may fund only KML 
hardware and software, end pechapy Acorn machines with BBC BASIC. Something like 
this may happen in the U.S.A, if Jupanese hardware becomes more popular. Cost is 
therefore not the only consideration, especially for achools. [t has to be anid that 
many people in the education sector have an unrealistic attitude to hardware wnd 
software, Letters are printed In the magazines from teachers who want to Introduce 
computing at a cost of £2 per head. There ja a widespread belief that schoola apend 
vast sums on technical gadgetry: video recorders, televisions, ond so on. The fact 
anema to be thet wayes and s#larius take the {lion's share of the huge suma paid on 
education, leaving net much for items Uke microcompulers. Often, parenta (vin parent- 
teacher assychitions) or companies whleb allot part of their budget te charities caa be 
persuaded to part with monry, Sometimes special furda for career trainiay or for 
yifted students can be tapped, The technique, 40 far avd know, is to (4) appoint an 





Wariware selutions are succesful with mont usars, and aro Likely ‘to romain bo untann 
iaitations hecems widsupreaty, The ‘dongle’ im a device Fitting une of the ports. ta 
ita eimginat form it might fit over the user port fehich La aore likwly to br free 
than tha JEEX port) and porhape ground Lhe diagnostic sonag pin, This enanid be checkod 
by the prograa (nh the seme way that the roeet routine avliects between AAGIC and the 
sonltor (er - urlgtinally - the diagnaet$c ruoytine), and, lf aot grounded, eraae Une 
progres, More @dophiatioate verslony aight Loclude timera and other circuitry, RGMa, 
28. in slot 800G-9FF7F, can aupplement the security of dink ayeteps, and Incerporata 
an identifjcation nusber, although EPROM copiers Hake thes lens than foulpront. 
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nthusiast willing to do the work, and (b) encourage this person to approach likely 
curces of funds at as high a level as possible, telling them that the aim fs to develop 


heir skills in this field or that. 


7.2.2 Programs, 

“Wwe found mest of Blanksoft's programs were execrable" (MB) 

‘omputer Aided Learning (‘CAL'), programmed learning, and teaching machines were 
irst introduced in the sixties, and appear to have been 4 near-totalt failure. Present 
echnoloyy at least offers the nope of greater success, but this cannot be taken for 
‘ranted, This section discusses some of the qualities which good educational software 
an be expected to passess, and some of its promising applications and topics. 

(i) Multiple-choice questions. Because of their ease of marking. tests of this 
ort are fairly popular. The principle is simple enough: a question Is posed, and @ 
mall number, say four. alternative ‘answers’ offered. Only ane is supposed to be 
orrect; the others may be deliberately chosen, perhaps empirically, to resemble the 
orrect answer clescly. or to be the correct answer to a slightly different question. 
‘he simplest scoring method is to give 1 mark for # correct solution, and deduct L/3 
fa mark for each incorrect question, where there are four alternative answers. This 
sa so-called ‘guessing correction’, The rationale is that a respondent who answers 
juestions at random will on average score 0, because three incorrect answers will just 
‘ancel out a single correct guess. In this way, reckless guessurs are “ot rewarded. 

\ language like Pilot (see appendices} can be used to generate programs of this sort, 
ithough some versions of Pilot may not enable scores to be kept. 

(2) Tests graded by year ond subject. A general questicn-and-answer session, 





yrovided as an off-the-shelf package, may be valunble. There is no need to adhere 
oa strict formant; there may be calculation questions, vocabulary questions, compre- 
lension questions. Ideaily, therefore, several! different programs on (say) second-year 
xconomies could be available, ta be used by a student for self-assessment. Programs 
ike this are quite difficult to write, and a standardised approach is vital if any sort 
xf reasonable productivity is wanted, : 

(3) Packages explaining single concepts. Many scientific, mathematical and 
inguistic concepts can-be made the sudject of prograns. Where the screen editing 
ind graphics capacity is used well, the resulting program may be a valuable supple- 
nent to a lesson. Examples include: i. A program to demonstrute how histograms (bat 
tharts) vary as the scales on which they are plotted, and the number of bars used. 
thange. il. Demonstrations of the relationships between the frequency of a sound and 
ts pitch, including intervals such as thirds and octuves. iii. Simutations using random 
wmbers. Any probability distribution ean be tried; examples include the uomnal 
tistribution, elementary distributions involving coins and dice, biological population 
nodels, and mathematical reautts derived from physics and chemistry. iv. Graph 
slotting: the iden of co-ordinates, the use of rectungular axes, the equations of some 
jimpler curves. v. Series summation and the idea of a limit’. Special casis can be 
ooked at: pl, e, and the golden section. vi. Concepts of calculus: differentiation can 
ye taught as the calculation of the limiting gradient at e@ point, and integration as the 
iddition of lengths, areas, or volumes of arbitrary smallness, vii, Mathematic | eco 
nomics. Supply and demand curves and deductions from them, fixed and variable 
sosts, average and marginal counts are all readily coniputeriyable as demonstrations, 
ore complex simulutions, such ny the ‘business cycte', can be illustrated too, 

viii. Simple ilngulstis Ideas. Languages generally are tao complex for tnicrocomputers 
iO get much purchnse on, but useful programs cun be written in restricted arnad, 
guch as voenbulary end trannintion testing. A succeasful program to test knowledge 
of German numbera (printing the cerrect German version of a written Aumber, high- 
dghting the response where it was incorrest) iustentes on sort of approuchk, 





§7.32,3 Genoral attitudes 

"Oe ig worthwhile to be aware of the two fundamentally different underiying 
attitudes possessed by converts to the cause of microcomputers In educotton, Both 
make claima whleh muy be suspected to tbe excessive, The first group conearna itaalf 
With supplementary training courses far teachers, with organising pupiis so thol enen 
af the older pupils in allotied a certain amount of thas per week. nant with tanvert lng 
pther denehers, This group Is tikely to produce popular programe, ciiee the aord 
subtle pitfalia require m fairly hard-Acaded appresch to detect and avobs, Their 
argumenta In favour of microcomputers read like Unba: Mlermcompiiters are unaparnlleied 
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at teaching logical thought. They provide great opportunities for students to display 
their creativity. Learning about microcomputers may be the most important part of 
their schooling. .. 

The second group has a more rumantic approach, and {is less concerned with 
matters of cost or pupil access, or of trying to assess the benefits of computer 
education. One pictures a roomful of ‘disadvantaged’ children, al! concentrating on 
their computers, and in fact playing a number game. This group's argument for micro~ 
computers reads: It is quite remarkable to see them working in an orderly way for 
hours. With microcomputers, increased equality of education is possible. Children 
who dropped out find their interest reawakened, and theie confidence grows... 

As far as teachers who are not involved in computer studies are concerned, 
microcomputers may be thrust upon them either by way of packages of the sort 
previously described, or in an administrative roie, Programs to help plan timetables 
illustrate this latter category. A few hints show the sort of approach which may need 
to be adopted when planning educational software which has to receive these peoples’ 
approval. In the first place, the cosmetic side of programs needs some attention, 
Lively and interesting graphics make a great deal of difference in all subjects, but 
perhaps particularly the more concrete subjects like biology and geography. Good 
graphies effects unfortunately are not casy to achieve. Another aspect of a program's 
appearance is the text: the CBM is fortunate in having lower-case, which is gencrally 
more readable than capitals ‘only. Attention should obviously be given to the wording: 
it is not only teachers of English who object to being told ‘Please get it rite’ or 
asked to enter ‘Any >» A,B.C,D'. Sometimes teachers may be worried about the mach- 
ine taking over from them. For exampie, they may reject a system which gives the 
student references on the topic under discussion. They may take the view that such 
information ought not to be issued too treely. 

A great deal of software has been written, and software directories and indexes 
appear from time to time in the computer press. The U.K. reader interested in finding 
out more should contact this address: 


The Council for Educational Technology 
3 Devonshire Street 

Landon 

WIN 2BA 

(Tel: (01)-636-4196) 


Explicitly Commodore-retated Information can be odtnined direct from Commodore 
or their dealers. MUSE (Microcomputer Users in Secondary Education) is what it says. 
Other interested parties include CAL News, based at (mperial College Computer Centre, 
and the Association of London Computer Clubs. I haven't listed addresses for these 
organisations, many of which sre rather mobile. 
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TABLE OF OPCODES AND THEIR FUNCTIONS, BIT SYRUCTURE, HEXADECIMAL VALUES, TIMING AND PROCESSOR FLAGS 

























































ROL_ Rotate memory or A one bit teft, inc, © Cotbbbin = N 
ROR” Rotate memory or A one bit right; ine. C”  6tibbb10 N™ 
RTI Return from interrupt or0000d00 NV BOT 
RTS Return from subroutine called by JSR g1laagoo 

SBC Subtract memory and C-complement from Aillbbbd! N V 





> — 
Opcode Deseription Bit structure Flags a a 
NV BDt2Z x 
ADC Add memory with carry to accumulator Ollbbbo1r N V z 
AND Logicai ANO memory with accumulator DOTbbbo1 N Zz 
ASL Shift memory or accumulator one bit left O0¢bbbIC N z 
BCC Branch if carry bit clear 10070000 
BCS Sranch if carry bit set: Toridaod 
BEQ Branch if zero bit set 14110000 
fIT AND with A, storing Z and bits 6 and 7 OO10b100 MIMS z 
BMi Branch if N (negative) flag set 00140000 
BNE Branch if zero bit clear = = SCH FOOD oe 
BPL Branch if N bit is not set o0010000 
BRK Force break to IRQ occoogod 1 1 
BYVC_ Branch on internal overflow bit clear 01019000 
‘BVS Branch on internal overfiow bit set ~~" 01711 6000°° 7 ss 
CLC Cfear the carry bit ooo07?000 
CLD Clear decimal flag (far hex arithmetic) ¥10T1000 6 
ELI Clear interrupt disable flag 001000 o 
CLV Clear internal overflow flag 16111006 ‘0 ” 
CMP Compare memory to accumulator 110bbb01 oN 
CPX Compare memory to X register 1110bboG KN 
cPY_Compare memory to Y register 1100b600_N 
OEC Decrement memory location “"™" TIOBBTTO WW a H 
OEX Decrement X register 1TO0tTGTO WN | 
DEY Decrement Y register tooo1d00 ON at 6lsi*s: 
EOR Logical exclusive-OR memory with A O10bbbol N : 
INC Tacrément memory Iccation “a ~FTTebI10- NT Z 
INX Increment X register 11101000 N Zz 
INY increment Y register 11001060 N Zz 
JMP_ jump ta new address 61b01100 
ISR Jump to new address, saving return d05100000 ~~ 
LDA Load accumulator from memory TOtbbbOl WN 
LOX Load X register from memory 101bbbig N 
LOY toad Y register from memory 101lbbboG ON 
CSR Shift “memory or accumulator one bit right @10bbhid” “9 ~~ ey Sas) o 
NOP No operation 13TO+OID { 
GORA Logical inclustve-OR memory with A Q00bbbOot N 
PHA Push accumulator onto stack ss NT HDD 
PHP “Push processor status flags onto stack ~ 00001000 °° ~~ 
PLA Pull stack into accumulator Q1toidgd N 
PLP Pull stack into processor status flags od1cl1G00 NV 8 ODI | 
: 





SEC Set the carry bit OO1II000 0 TTT es 

SED Set the decimai flag (for BCD arithmetich (1211000 i [ 

SE) Set the interrupt disabie flag O1i11000 1 

STA Store accumulator into memory FM bbOS : | ees core 

5TX” Store X into memory Sc a 1) ae ; 

STY Stare ¥ Into memory TOObbI0G . | 

TAX Transtar accumulator to X register TOrolgld z j 2 

Transfer _sccumulator to v prolater = poration N Zz J : — n alensees | ;. re oe 
SX Transfer stack pointer to X register ~ ~ POfHOSO QO TTT oe H ; : 

TXA Transfer X register to A 1Qourhig ww Z : : 5 _ ee ne aA a 

TXS Transfer X regiater to stack pointer tanlinio : Noma oe. 3 : pa pay 2 | 
TYA Transfer Y register to A 1011040 ON z : Eo meg ieee 
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Low High Low High 
Hex Dec. Dec. { Hex Dec. Dec. | Hex 


DECIMAL - HEXADECIMAL INTERCONVERSION TABLE 


PAA TELE PRE a Rae A NT PTTL GE PA AT TELE TEEN TRYIN EE TT UT eS 


18] 4608 
19| 4864 
20) 5420 
$376 
§632 
5888 
6144 
6400 
6656 
27) 6912 
28) 7168 
29: 7424 
30! 7680 
21 | 7935 
42 
33} 8448 
34} a704 
35| 8960 
36} 9216 
37] 9472 
3a| 9728 
39! 9984 
40 |10240 
41110496 
42 |190752 
43111008 
G4 1b 2646 
4511520 
4G [11776 
47112032 
4g ]12288 
a9/12544 
§0)12800 
St |13056 
52433312 
$3 /13566 
64 (13824 
5$ [14080 
56 114436 
$7(14597 
Sa] ladue 
69115804 





pra7z~ 


$40 
$41 

S42 
$43 
say 
$45 
$46 
$4? 

$aa 
S49 
S4A 
$4B 
$4c 
$40 
SHE 


SaF 


$50 
$51 
$52 
$53 
$54 
$55 
$56 
$57 
$58 
$59 
$5A 
$5B 
$sc 
$5D 
$SE 
$5F 
$60 
$61 
$62 
$63 
$64 
$65 
$66 
$67 
$68 
$69 
$6A 
$68 
56C 
$60 
SE 
$6F 


$70" 


$71 

$72 
$73 
$74 
$75 
$76 
$77 
$78 
$79 
STA 
$7B 
$7C 
$70 
STE 
$?7F 
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low High Low High 

Dec. Dec, Hex Dec. Dec, 
64l163a4 7 $e0 [428;32768 | $CO]192 49152 
6516040 $81 }129/33024 | SCI ]193;49408 
66ligs96 | $82} 130/332z80 | $C2}194! 49664 
6717152 $83 | 131533836 | $C3]195/ 49920 
68/1748 | $84 | 132;33792 | $C4) 196 )50176 
69/1766 | $85 |133;3¥o4a | $C5|197/50432 
70/17920 | $86 |134-34304 | $C6} 19850688 
71 [18176 | $87 | 135134560 | $C7}199:50944 
72|18432 | $88 |136:34391G | $Ca]200,51200 
73; 18688 $29 137 | 35072 $C9 | 201°51456 
74118944 | $84 | 138)35328 ; SCA| 202151772 
75/19200 | $8B [139 35544 | $CB/ 203151968 
7el19us6 | $8C/140/35840 | $cc 20452224 
W7H19712 | $80 134136096 + $CO] 205|524a0 
78|19968 } $8E / 14236352 | SCE | 208|52736 
29] 20224 f S8F (143:36608 | SCF | 207152992 
Go/2048d {$90 / 1kai3ea64 | S00 | 208 /53248 
81)20736 {| $91 }145/37120 | $D1 | 209!53504 
82/20992 | $92 1146,37378 | sD2! 210153760 
83|21248 f $93 | yu7 |37632 $03 | 21154016 
g4/21s04 | $94 | tuB)a7aea | $04 | 212:54272 
85j24760 | $95 }149/38149 | $D5]213:54528 
a6(22016 | $96 /150/38400 | §D6 | 214|/S47a4 
87!22272 | $97 [151134656 | SD7}215)/5S040 
98;22528 | $9B [152438912 | sp8 | 216|55296 
89/22784 | $99 [153:39168 | $09] 217155552 
30|23080 $98 154 (39428 SDA | 218 |55808 
91}23296 | $98 |155/39680 | sDB}219)S6064 
92;23552 |] $9C /156/39936 } $DC!220:56320 
93123808 | $90 |157|40192 | $00] 221:56576 
94124064 | $9E |158|40448 | SDE {222156832 
95/24320 4 $9F |159/40704 | SOF | 223157088 
96;24576 | $A0 [16d 40960 f Sen [224 [s73u4 
97124832 | $At|161/41216 | $E1 | 225)57600 
96;25088 | $A2|162:41672 | $E2 226 {57856 
99}25343 | $A3|%63/41728 | SE3 | 227/5a112 
100/25600 | $A4|ie4'4i9e4 | SE4 1 228'58368 
101;25856 | SAS |165!422490 | se5 | 229'54624 
102|26112 | $AG|166/42496 | $E6 | 230; SB880 
103/26368 | $A71167/42752 | SE7 {231159136 
to4}26624 | $A8]168/43008 | S$Ea | 232!59392 
105/268e0 | $A9]169|43z64 | $9 | 233|soaKe 
106!27736 | $AA]/170/43520 | SEA | 234/S9904 
107/27392 | SABli71]aa776 | SEB | 235 :69160 
108|/27648 | $AC/172/44032 | SEC | 235 |KD416 
109:27904 4 SAD|173! 44288 | SED | 237 (60672 
110728160 } SAE {174)44544 | SEE | 23860928 
iy /2euis f SAF [175] 94800 | SEF (23960184 _ 
112!28672 °} $Bo;176/45056 | SFO | 246 |at4uo 
113/78928 { $B} 1177/495312 } SFI 12411618696 
144|29184 | $B2|17Hiuss6a | SEZ} 242161952 
t1s/2z94490 | saa j179l45a24 | SF3 124362208 
116:29696 | siuftaoiseaso } $Fa | 244 l62464 
167/29952) | $85 11B81/46316 | SES 1245 162720 
118] 30208 SUG [1E7, 46592 SFG [246 62976 
W29:30q64 | 47 |183)HGANa | SFF [247163232 
120!30720 | $88 |1a4|4a7i04 | SFB 244361488 
121|30976 sa jiaslu7aso | 5F9 249163748 
122;31232 | SBA] 1R6) 47616 § SFA] 250! 65000 
yz3lgiwaB } SQG]1R7)a7B72 | SFB] 251164256 
12a) J17ag | SHC | 1A} WaT 28 gFC | 752164552 
125/32090 | saDsissjuaisa | SFO] 253) 54768 
126| 32256 SHE [190] 49640 SFE | 254 [64024 
q27}a7siz | se [iatiweaes | SFR | 255 ]e5780 
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OPCODE HIGH NYBBLE 
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‘agromming the PET /C8M ~486- Appendices: the 6502 Programming the PET /C8M -487- Appendices: the 6502 





6502 TIMING: QUICK REFERENCE CHART 


ADDRESSING TIME ... we» EXCEPTIONS 
MODE Dec, Inc, Rotate, Shift Others 
Absolute JMP=3 JSR=6 
Abs,X and Abs, ¥| 4 (+1 over page} STA = 5 


Zero Page 
Zer,X and Zer,¥ 


a 
EXAMPLES OF ADDRESSING MODES WITH THE 6502 


———— a re: 


bsolute i. CPX $12CF Compares the contents of the X-register with that af 


location $12CF. Both X and Si2CF are unchanged, and the N,2Z,and 
C filaga are reset. The point is that the ‘absolute address’ is used. 
il. STA $8000 Stores the accumulator in iccation $8000. 
ti. JSR WALT Assembler notation for a subroutine call to 'WAIT', 
which the assembler identifies as a 2-byte address. 

Esolute,X 1. LDA $FF00,X The X register is treated as an offset; its value 
(0-255) is added to SFFOO, and the accumulotor loaded with the byte 
found at this new address. Thus, if X holds #3®5, in the example 
the accumulator will be loaded with the contents of SFFFS. 

li, ADC $7106,% Adds the contents of $7100, offset by X, plus the 
earry bit, to A. The result remains in A. This indexed instruction 
(like all such instructions) provides easy access to a range of 

: addresses, in association with DEX, INX, and related commands 

bsolute,Y i. ULDX TABLE,Y Absolute addressing indexed by Y is exactly analog~ 
ous to X indexing, although fewer opcodes have this facility. In 
the exampie, X is loided with the byte at TARLE+Y. 

ii, STA $8000,Y Stores the accumulator into a location between $8000 
and $80FF, depending on the current value held in Y. 

















Stack PH=3, PL=4 
Oa RT556 RT1=6 
Immediate ete BRK-7 
Relative ; 2 Cif no branch}/ FE - ; a 
3 (if branch taken f° ~ 

+1 over page) 


























Accumulator 
(ind, X) 





ero page T. EDA $70 Loads A with the contents of location $70. 
it, SBC $43 Subtracts the contents of $43 from A. (Ind},¥ § {+t over page) STA (ind},¥ =6 


Sale lle gt nlm de. eget ar sl, tl AR i Meena Ie TE ATE ET. - Te : 


Wit. ROL 2PG 128 Unusual assembler version of what normally appears 
as ROL $80, which rotates the contents of $80, and C, to the left. 

ero page.X i. INC $t5,X Analogous to absolute addressing indexed by X, 
except for the use of the single-byte address to which the offset X 
tg added. BUT only zero page addresses are generated: if X holds 
#$0A, then $15,X refers to location $1F. However, if X holds #$F9 
then $15.X is address $05, not $0105. 
ero page,Y i. LDX $AB,¥ Only two instructions can use this mode. Both involve 
ik. STX $10,¥ the X register. The operution of register Y on the 

. zero page address js exactly similar to the previous example. 
nplied T. GRR A large number of instructions do not operate on external 
i. CLC RAM or ROM, but on flags, registers, und the stack, which 
li. PHA are internal to the chip. Other examples: TXS, SEI. CLD,INY. 
mmediate. 1. LDA *$ Assembler form of instruction to Ton wit : 
il. LDA #$30 Londs A with hex 30. The third example is from a 
Hi. LDY iMM 48 dectknut assembler which quotes the mode, rather than 
let it be deduced by the form of the instruction. Note that immediate 
mode is the only mcde handling direct duta values, 


(Absolute) 5 








oars 


All figures are clock cycles {one millionth of a second for CBM computers) 








: PROCESSOR STATUS REGISTER 





ar 


} Example: A processor status register (SR with CBM's monitor) of 32 hexadecimal 
means that the Break flag (B) and the zero flag (Z) were sct on entering the 
monitor. Some of the combinations may at first sight appear impossible; how 

+ ean the negative bit (N) and the zero bit (Z) be simultaneously on? But the 
BIT opcode can accomplish this; and generally PHP can be used to set flaya. 


76543710 

















velative T. BEQ $0794 Branches tu $0294 if the zero flag is set; the next 
WW. BCS LI example {a an assembler version, branching to a label. High nybdbdle 


HI.BVC #117 This last example shows a different convention, which ees 
corresponds ta the way the opcode is stored, Here, there's an offset 


of 117 bytes forward from the eat instruction, 


‘ccumulator I. LSR A few commands acton the contents of A, elther rotating tt 
il, ROL or shifting It, If can be considered an_bmptied mode. 
ndexed T. ORA (500, X) Displacement X is added (o the zero page address, to 
Indirect give a new address In the zero puye. This uddress, and ith aub- 


sequent byte, together point te an abedlute uddrass whieh {in the 
example) Is ORed with A. Tf there ds a collection of paliters In the 
zero page, this is useful. When X nalds sero, the made beesmen in { 
effect stralghtforward Indirect addressing, Example: X hata #5, | 
location § holda #3, tocation & holds 124, LOA (4$00,%) lowds the 
eo ee CCUM Lor fram SAVOL. 
ndirect T. LBA ($12),¥ The address Tn (81277 that Tx, having $3 contents 
indexed as ta high aud $12's an its low byte, pilus the offset within %, fa 
acceused and loaded inte A. This Is uxeful when desing wlth HAM 
data arranged consecutlyely, og. mesanges and fablen. 
(Bsolute ToTIMP ($0090) Onty JMP BC flex used this meade. In tha exampfe, | 
Indlrect $9U holdn #SZE and $91 holds IE0, IMEC SHINO) Jumps to fEB2E, 


es 0 re re 


J 
2 
3 
6 
? 
A 
B 
E 
F 





a 
9 
A 
8 
c 
ie) 
E 
F 
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2rogranuning the PET /C&8M -488- Appendices: the 6502 


FURTHER ASPECTS OF THE 6592 


‘Wy ROR. 65929 mnde before 1977 may not possess this command. Machine-code is 
herefore sometines written without it if there are old 6502s in the field. 'Byte' of 
lune ‘81 has an article on an Ataci BASIC with ROR replaced by equivalent code. 
2) JAP, There is a bug in the 6502's processing of the indirect jump ($6C) 
ngtruction, When the indirect address straddles a page boundary, the high byte 
& taken from the address in its own page. Thus, JMP ($Q3FF) junps to the new 
iddress whose low byte is in SOUFF, as it should be, but whose high byte comes 
rom $0300, not the correct $0400, No CBM code contains a jump of this sort, * 


3] Addressing modes. Examination of tables of opcodes shows that there are many 
veriedic patterns in the distribution of the codes. Given the way logic circuits work, 
his is not surprising. All those opcodes which have more than one addressing mode 
ite dependent on bits 2,3, and 4 to determine the mode; the tabie following shows 
he relationships. If the addressing mode doesn't exist for an opcode, then that 

sart of the table does not of course apply: 


Opcode = xxxbbbxx Values of Obb represent: 



















10 Immediate/ Accumulator 
0G (Indirect}),Y er when followed by 09, Relative 
Ol Zero Page, X 
10 Absolute, ¥ 

11 Absolute,X 
— a ae 


4) Pseudo-Opcodes. The sequential tables of opcodes and addressing modes omitted 
‘clumnsa corresponding te -3, -7, -B, and -F. This is for the good reason that the 
ianufacturers do not specify any function of the chip corresponding to these values. 
‘here are other gaps in the table: in fact, only 151 opcodes sre implemented of the 
sossibfe 256 (ar more) maximum. Nevertheless, many pseudo-opcodes (for want of a 
wtter termappear to exist, though the makers don't encourage correspondence on 
his point, [PUG (Jan '31) published an article by B Grainger on empirical work done 
mn the 6502, in which descriptions accompanied by 3 letter ‘opeudes' account for 93 
f the 105 mystery values - if they are correct. For those who are interested in 
reana of this sort, [ present later tne substance of his article with notes on timing 
tid testing pseudo-opcodes anu possible applications. In the absence of theoretical 
inderpinning it is hard to know where to start on such un investigation; fur one 
hing there is no guarantee that a non-stundard code will not behave in entirely 
Inexpected ways, corrupting reyistecs perhaps, or executing repetitive, meaning~ 
ess loops, lke ‘Halt and catch fire’ on the 280, 


im Butterfield has poinfed out that endes ending in bits -L1 simultaneously execute 
wo commands, those ending in -01 and In -10. (Except that the timing may fail in 
ome circumstances, transferring only 6 bits), All codes ending -3,-7, -B, and -F 
re of thls type. This means that that a pseudu-opcode ending in -A, buy, may 
ombine the functions of the two coder ending -6 and -9 next to It. Something 

imjlar scema to happen in other cases not of this type. The XZ crosh, for 
natance, in which an opcode ending -2 cuuses the chip te loop indefinitely until 
nterrupted, appears to operate by virtue of the fact that all the branch commands 
nd with -0, and are near neighbours. And the 'SKW' or skip word pxeuda-opcade 
thich skips over the next two bytes and ‘SKA! which skips ene byte are each 
ound, respectlyuly, in the obsulute and zero puga area of the opcode table, 
uggeating that some of these pxeudo-codes may currupl one or two memory 
xentions. 


i Post-indexed 


or when followed by 00, Implied 





‘T bave heard that there (@ a bug related to une of the registers, but know 
iOthing etme about tiie alleged an} functian, 


TE INET EE EE II AL SION AE EE AN a AE IIR RYE CR EE PONTE TO MINN eee 


See Bb ane, Oa ai 


iAP ck a 


~489- Appendices: the 6502 


Programming the PET/CBA 


6502 PSEUDO-OPCQODES* 









Abs Abs,X Abs,¥Y Zer Zer,X Zer,¥ (Inc,X) (ind), Y fmm 


QF IF 1B Q? tt? Og ts 68 
2F 3F 3B 27. «37 23 33 28 
AF SF 5B a7 57 43 53 a8 
6F  7F 1B 67 77 63 74 6B 
8F a7 97 83 

LAX (LDX,CDA) | AF BE AT B? AY B3 

DCM (DEC,CMP) | CF DE DB OCT) OD? ca D3 

INS CINC,SBC) |&F FF FB E? F7 E3 F3 

ALR (LSR,EOR) 5B 
ARR {ROR,ADC) 6B 
XAA (TXA, ) 8B 
OAL (TAX,LDA) AB 
SAX (DEX, CMP} cB 


NOP 1A, 3A, 5A, 7A, DA, FA 
SKB 80,82,C2,£2,04,14,34, 44,55, 64, 74, Ou, Fa 
SKW oc, 1, 3C,5C, 7C, DC, FC 


The table shows some pseudo-opcodes, Those in bold type are more credible than 
those which are not. Probably, most anomalies will occur when addressing modes 
of neighbouring opcodes, er their timings, don‘t match. For instance, the cude 
BF, combining LDX Abs,Y with LDA Abs.X might be expected to give an odd 
resulting addressing mode, particularly if one or both instructions crosses a page 
and so takes another clock cycle to execute. The ‘mnemonics!’ given in the table 
have the following significance: 


ASO ASL then ORA the result with the accumulator 

RLA ROL then AND the result with the accumulator 

LSE LSR then EOR the result with the accunulator 

RRA ROR then ADC the result to the accumulator 

AXS Store the result of A AND X 

LAX LDA and LDX with the same data 

DCM BEC memory and CMP the result with the accumulator 
INS INC memory then SHC the result from the accumulator 
ALR AND the accumulutor with data and LUSK the result 
ARR AND the accumulator with data and ROR the result 
XAA Store X AND data In the accumulator 

OAL ORA the accumulator with 4$EE, AND the resu:t with data, then TAX 
SAX SEC data from A AND X and store resuit in % 

NOP No operation 

SKB Skip byte (le brunch of +1) 

SKW Skip word of 2 bytes (ie branch of +2) 


Many of the codes show repetitiveness, derived from regularities in the 6502, but 
there ure muny one off possibillties too: 9A combines TXS and STA Abs, ¥ will the 
net effect of storing 'A AND X in the atick pointer and bit Ocf A AND X in 
memory’. 


Instruction 


ASO (ASL,ORA) 
RLA (ROL,AND) 
LSE (t5R,EOR) 
RRA (ROR,ADC) 
AXS (STX,STA) 
























Applications. These commands are not part of the chip'a specificntlon, sa they 


stouid Dost De AvGlded in machines code routined for sate or generat use, somelimes 
they wre helptial it debupying mochine cade, when a jumpoor branch has bern trken 
toa wren uddeess, Mainly, though, thar potential appteation Hes in the fnet that 


hhiiden routines - toe print out Identilcation mensiges, or save a progam Using 
Apecial webnkpue, for exemple - for Woe programmer's use only can be written in a 
way which disassemoters will be unable tu decipher easily. 


“Mune of ‘the mnemonics and dascriptiona arc froa { Craingar's Jan. ‘Br Peo 
article. 


q = 
STR AT ee TEE TTS EN et ee NP RR A me ee REPT PI AED, ALAM A Hehe SA EE ER 











708 60 AZ 62 BS FA 4& BD CA]S80 79 DS 26 D7 20 33 DIFFS 835 93 AD AD BD 4E FE CEqyR7O 86 DG F3 AS PE $1 FBZ ! 
710 02 95 FA 68 9D 0A 02 CA]88E AZ 00 OO Ai FB 20 74 FCJAOO 15 EB AS 2ZE BD 48 EB AIB78 64 FC 00 35 FB a4 FC AD 
§718 DO Fl 60 AD OB O2 AC OC] B90 00 48 20 BR FC 00 6&8 20)/A03 OG 00 SD 49 FB AE 06 02;B80 41 20 79 DS 29 17 ©? zo ; 
£720 02 4C CE FA 0G AS FD A4/898 93 FC 00 A2 OB EO GS DOYAIO SA 4€ 55 DE 20 CO FC 5E,BS8 31°05 4C DS FO ¢2 AG 20 ' 
2728 FE 38 ES FB 80 1B 02 98/940 13 AC 1C O2 FO GE AS FFEAIS 8D 05 G2 68 8D 04 O72 GEIBSC EG FE OG DO i! 58 FO CE i 
2730 E5 FC AB OD 1B 82 60 20/8A8 C9 ESB Bi FB BO IC 20 SCPAZD BD O3 O02 6B AD O2 O2 648896 £6 Be AGB BS ID 3:¢ O02 08 
“738 Bi FA 00 20 44 D7 20 92$B8RO FC 00 88 DO F2 06 FF 304428 BD 01 02 68 BD 00 00 2,B40 £9 Be BS AG E4 78 60 C9 
n740 FA 00 20 AF FA 00 20 92)8BB OF BD $1 FF OO 20 45 FRIABO BA BE 06 O02 5A Z0 34 DS5,bAe 30 90 03 CS 47 60 3B 60 
748 FA 00 20 CA FA 00 20 44]/8C0 90 BD 57 FF 00 FO O03 20/438 20 23 DS 85 BS AO OO GOTRRO 40 02 45 O02 DC OR 40 29 
0750 D7 90 135 AGB DE NO 635 20]/ecs 45 FD OO CA DO D4 66 20/440 20 FE D4 20 31 DS AD OOFRRSB 30 22 45 33 DO OB 40 09 
$758 Cl FA 06 90 60 AL FB 81/8D0 68 FC 00 AA EB DO 01 CAlA4B 00 O2 BS FC AD O1 O02 BSIBCO 40 O02 45 33 DO 08 40 09 
&760 FDR 20 A& FA OO 20 39 DS|8DB 38 20 SC FC OG BA SE B4PASO FB 20 17 OF 20 OF FC popes 40 02 43 B3 35 08 40 oF : 
=768 DO EB 20 Cl FA 00 £8 ADJSEO 20 22 D7? AB B4 G6O AD 109458 20 35 F3 C9 FF FO FS 203509 O00 00 22 44 33 DC BC 44 
770 1B 02 65 FD 8&5 FD 98 65/8ES 02 38 Ad FC AA 10 01 BAISEO 35 F3 DO O3 4C BA D4 CIipDe OO DO it 22 44 33 DO at é 
77B FE @5 FE 20 AF FA OO AG] SFO 65 FB 90 O01 CB 606 AB 4AlA4ES FF FO FA 40 SB FD 00 20,;RE0 44 SA i060 22 44 23 DO CB f 
780 DE PO 3D Al FB Bi FD 20/&F& 390 OB 4A BO 17 C9 22 FOJ470 Bi FA OC 20 44 DZ BE 1i}BEg 409 0S 10 22 44 33 BD 08 
788 Ci FA 00 80 34 20 65 FAI9G0 313 29 07 09 80 4A AA BDIA7S 02 AZ OA 20 79 FA OO 4B°EFO 40 09 &F 13 > Ag GO 00 
790 00 20 68 FA OO 4C 1B FRI9JOB OG FF GQ BO C4 48 44 4A/A80 CA DO FS AZ 03 66 328 ESBFS 21 Bi 82 00 OC CO oo 39 i 
798 00 20 A! FA 00 20 44 D7}910 4A 29 OF DO 04 AO BO AS|AaB BF AD OS 4A GE 11 O2 GEICOD 4D 91 92 BE 44 BS 9D 2C 
7A0 20 92 FA 00 20 44 DZ 20)918 0G 00 AA BD 44 FF 00 85/a90 10 02 8& BO F6 CA DO EDIcos 29 2C 239 28 24 59 00 00 
~7A8 98 D7 20 63 D?% 90 14 BS5/920 FF 29 G3 BD iC 02 98 29/a98 az? oF 20 CF FF C9 OD FOoitiO sa re 24 00 O06 1C Ba 1C 19 
780 85 AG DE DO 1: 20 CA FA]92S8 BF AA 9S AO 03 EO BA FCfAAO 1E C9 20 FO FS 20 F? FEICIS8 232 5D SB 1B Al $D BA JD k 
* 788 09 90 OC AS BS Bi FB 20/930 OB 4A 90 08 4A 4a 09 Z6laay 00 BO OF 20 78 DY A4 FBICTO 73 9D BB ID A: 00 00 2 ' 
700 39 DS DO EE 4€ SA FA 00/933 S88 DO FA CB S& DO F2 BOLARG 84 FC 85 FB AS 30 9D 1olc2a 19 AE 69 AB 1S 23 24 2 
7C8 4C BA D4 20 81 FA OO 20/940 Bl FB 20 SC FC 0G AZ O1JABa O2 ES 9D 10 O2 EB DO DEC3BO iB 23 24 53 19 AL OO Of 
7D0 44 D? 20 92 FA 00 20 44/948 20 Al FA 00 CC 1€ O2 CAJACO BE OB Of AZ OO OO BG PEICIS tA SB YB AS 69 24 4 AE 
7D8 D7 20 98 DZ AZ GO 00 20/950 90 FO AZ O2 CC OS O2 9OlAca FO O4 FE DE FO 7B AZ OO}C30 AE AB AD 29 00 GO 7C 00 
7EO 35 D7 C9 27 DO 14 20 GAISSS FO 60 AB BY SE FF 00 SDIADO OO BS& FS AS DE 20 74 FCiC4A OO 135 9C BD 39C AS 69 2d ; 
7E8 D7 GD 16 62 ES 20 CF FFI960 OB O02 BS SE FF OO BD OCIADS 60 AS FF SE OC O2 AA BCICSO 53 84 $3 34 11 A3 &F 22 } 
7FO C9 OD FO 22 EO 20 DO F1]968 O02 AI OC OO AO OS OE ACIAEO SE FF 00 BD SE FF 00 Z0jCES ad DS 62 SA 48 2S 62 94 Ff 
= 7Fs Fo 1C BE 00 00 Of 20 6B)970 O2 ZE OB O02 ZA 88 DO FEIAES EO FE 00 DO E2 AZ OB ECICEO 58 f4 44 C9 44 GA a4 EB 
© 800 DF $0 C6 9D 10 O2 EB 204978 69 SF 20 D2 FF CA DO EAJAFO O23 DC 'H AC 1C OF FO 15]CG6H 94 09°00 Be O8 OA4 74 Be ’ 
808 CF FF CS 0D FO G9 26 63j/950 4C 31 DS 20 81 FA OO ZOJAFS AS FF C9 ES AD 30 BO PiC7TO 29 SE 74 FH CO 4A 72 FZ 
4810 D7? 90 BE ED 20 DO EC 861/988 44 D? 26 92 FA 00 20 44)R00 20 EE FE 00 DO CA 2¢ Eaic7s a4 3A O00 09 AA ADP AZ 74 t 
“aia B4 20 34 DS A2 00 OO AQ}990 D7 AS O04 AZ OO 00 SD OS/B0aG FE 00 DO C3 SS De EB C&icao Fe 74 72 44 6B R?2 BC BT 5 
£320 00 00 BI FB DD 10 02 DI)3983 O2 BE OA O2 20 34 DS ZOfR10 FF 90 OR BC 57 FF 00 RPICSS GO CO 22 00 OO 18a 3A 2 f 
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ogromming the PET/CBM 


\sic 


ohne why 


2 SUPERMON OATA LOAOER. 


te: 


M 0028 0028 may give something Like: 26 74 03 G4 63 04 03 O04, where the atart 
dress is inconsistent. For compatibility with BASIC change 28 7A to O1 04. 


+ PRENT ®{REVSISETTING UP DATA FOR SUPER AMI...” 

> FOR J © F767 TO 33ST: READ ¥; PORE J45500,K: NEAT 

2 FOR J = 3767 TO S301: POKE J, PEEK (#5500); NEXT 

) PROUAT* (DOWN I IREYS {NOm RUN SUPERMON BASIC LOACER™: EMO 


> OATA 
' CATA 
2 OATA 
[ OATA 
+ OTA 
4 DATA 
+ DATA 
' DATA 
} DATA 
* DATA 
1 OATA 
| DATA 
! QATA 
| CATA 
| DATA 
+ DATA 
+ DATA 
' DATA 
t DATA 
1 DATA 
1 DATA 
| DATA 
) DATA 
+ DATA 
| DATA 
+ DATA 
» DATA 
' DATA 
| DATA 
} DATA 
} DATA 
CATA 
' DATA 
+ DATA 
i DATA 
+ DATA 
> DATA 
‘ DATA 
| DATA 
1 

t 


CATA. 


OATA 
DATA 
DATA 
DATA 
DATA 
DATA 
CATA 
CATA 
CATA 
Bata 
DATA 
DATA 
' DATA 
DATA 
DATA 
» DATA 
DATA 
DATA 
DATA 
DATA 
DATA 
DATA 
‘ DATA 
+ BATA 
DATA 
DATA 
DATA 
DATA 
DATA 
+ DATA 
I MATA 

DATA 
DATA 
DATA 
DATA 





173,255,254, 0, 133, 52, 173, 255, 255,0, 533,53, 173,255, 292,0, 141,250,3, 175,753 
253,0, 145,255,3,0,0,0, 162,8,221 , 255, 222,0,208, 14, 138, 180, 638,16, 170, 189 
255,253,0, 72,189, 255, 252,0, 72,98, 202, 16, 234, 26,247,235, 162,2,48, 162,0,6 
0,185,251 ,208, 6, 180,252,208, 2, 230,222,214, 232,214, 251, 96, $2,255,251, 20! 
$2,240,249, 96, 169,0,0,0, 141,0,0,0,1,32,250, 140, 0, 52,190, 251, 32,170,231, 148 
9, 96,32,255, 251,35, 157,231, 176, 222, 25,249,250, $2,209, 258,202, 208, 2 90,96 
250,253,208, 2,230, 754,96, 162, 2, 181, 250, 72, 189,10, 2, 149,250, 104, 157, 10,2 
202,208, 241,96, 178, 11,2, 172, 12,2, 76,250,221, 0, 165, 253, 164,254, 56,229, 251 
135/207, 152,229, 252, 168, 5,207, 96, 32,250, 148,0,32, 15,231 32,250, 16$,0,32 
250, 190'0, 52,250, 165,0, $2, 250,217,0,32, 151,231, 144,21, 166, 222, 208, 100, 32 
250, 208,0, 144,95, 181,251, 129,253,52, 250, 1B3,0, 37,213, 283, 208, 235,32, 250 
206, 6, 24, 165,207, 101.253.155.253, 152,101,254, 135,254, 32, 250, 190,0, 166,222 
208,61, 161,251, 129,255, 52, 250, 208, 0, 176, 52,532,250, 170,0,52, 250, 125,0, 76 
251, 39,0, 32, 250, 148,0, 32, 151,231, 32,250, 165,0, 52, 151,251, 32,235,251, 32, 182 
231,144, 20,195, 101, 166,222, 208, 17, 32,250, 217,0, 144, 12,165, 11, 129, 251,32 
213,253, 208,238, 76,247,231. 76,86, 255,32, 250, 148,0, 32, 151, 231, 52, 250, 165 
D, 32, (31,231, 32,235,231, 162,0,0,0, 32,235,231, 261, 39,208, 29, 32,255,231, 157 
18,2, 232, 32,207,255, 20), 13,240, 34,224, 32,208, 241, 240, 28, 162,0,0,0, 1,32, 190 
231, 144, 198, 157,18,2,252, 32, 207,255,201, 13, 240,9, 52, 182,231, 144, 102,224 
32,208,236, 134, 180, $2,208,253, 162,0,0,0, 160,0,0,0, 177,231,228, 16,2, 208, 12 
200,252, 228, 180,208, 243,32, 16,251, 42,205, 255,32, 213,255, 166,222,208, 146 
32,250,217, 0, 176,221, 76,88,255, 52,250, 148,0, 141, (3,2,165,252¢141, 14,2, 169 
4, 162,0,0,0, 13), 184, 134, 195, 169, 147, 52,210,255, 169,22, 133.181, 32,252, 16 
0, 32,252, 109, 0,133,251, 132,252, 198, 181.208, 242, 169, 145, 52,210,255, 76,46 
253, 160, 44, 32,21,254, 32, 106, 231, 32,205,255, 162,0,9,0, 161,251, 32,252,124 

0, 72, 32,252,194, 0, 104, $2,252,216, 0, 162,65, 224, 5,204, 18, 164, 182, 249,14, 165 
255, 301, 252, 177, 251, 176, 28, 32,252, (01,0, 136,295, 247,6, 255, 144, 14, 189,255 
74,0,32,253,77,0, 189,255,80,0,240,3, 32,253, 77,0, 207,208,215, 96,32, 2524112 
G, 176, 252, 206, 1, 200, 152,52, 252,101 ,0, 136, 134, 130, 32,117,231, 166, 189,95, 165 
182,36, (64,252, 170, 16,1, 156, 101,251, 144, 1, 200,96, 168, 74, 144,11, 74,176, 23 
201346240, 19,41, 7.9, 528, 74,170, 189, 254,249,0,176,4, 74, 74,74, 74,41, 15,208 
4,160, 128, 169,0,0,0, 170, 189, 255,61 ,0,133,795,41,3, 155, 182,152, 41,145, 120 
152, 160,3,224,158, 240,11, 74, 144-8, 74,74,9,32, 136,208, 259, 200, 130,298,242 
96, 177, 251,352,252, 101.0, 162, 1, 32,250,176, 0, 196,162,206, 146,241, 162, 3,696 
184, 144, 242,96, 164, 165, 255,47,0, 149, 11,2, 185,255, 151,0, 141,12,2, 169, 0,0 

8, 160, 5,14, 12,2, 46, 11,2,42, 136,208,246, 105,63, 32,210,255, 202, 208, 254, 5 
205,253, 32,250, 48,0, 52,215,255,32,215,253,32,191,231, 32,250, 165,0, 32,091 
231532, 202,233, 32, 230,217,0, 144,9, 152, 20B, 19, 183, 207,48, 15, 18, 7,700,208 
10, 165,207, 16,6, 32,117,231, 76,86, 255, 76,247, 251, 32,250, 148,06, 169,3, 135, 181 
32,235,231 ,32, 167,255, 208, 248,173, 15,2, 133,251, 173,14, 2,135, 252, 76,251,244 
D, 197, 185,240, 3, 32,210, 245, 96, 169, 3, 182, 36, 135, IBS, 134, 185,32,248, 255, 120 
193,255, 250,0, 153, 144, 173,255, 251,0, (53, 145, 169, 160,14), 78,252,206, 19,232 
169,46, 141, 72,252, 169,0,0,0, 41, 73,232, 174, 6,2, 154, 70,24), 254, 32,123,252 
10a! t4),$,2,104,141,4,2, 104. 041.3,2, 104, 141,27, 2, 104, 141, 1,2, 104, 141,0,0 
0,2, 186, 142.6, 2,86, $2, 208,253,52, 191,255,133, 181, 160,0,0,0, 32, 154,255, 52 
2055255,173,0,0,0,2, 133,252,053, 1,2, 533,251, 32,106,251, 37,292, 24,0, 32,1 
243,201, 247, 240,249, 32, 1,243, 208, 3, 76,96, 235, 201,255, 240, 244, 76, 245,96, 0 
0,0,0, 32,250, 148, 0, 32, 151,251, 142, 17,2, 162, 3,352,259, 140, 0, 72,202, 208, 249 
162.3, 108, 56,233.53, 1460,5,24, 110, 17,2, 110, 56.2, 136,299, 244, 292,204,252, 162 
2,58, $07, 255/201, 132-240) 36, 201 ,32,240,248,57,254,240,0.176.15,52, 205,255 
(64,241, 132,252, 135,251, 169,48, 157, 16,2,252, 157, 16, 2,252, 208,219, (42,11 

2, 182,0,0,0, 114,272, 142,0,0.0, 154, 1A) 185, 222,37, 252, 174.0, 166, 255, 142, 12 
2,270, 189, 255,151,0,52, 254, 213,0, 169,255, 47,0,32,254,715,0, 162,0,224, 5,208 
16,164, 19, 246, 14,165,355, $01,532, 165,48, 176,29, $7,254, 219,0, 156, 208, 242 
6,255, 144, 14, 189,255, 74,0, 32, 254, 213,0, 189,255, 60,0, 240, 3,52, 254,25 5,0, 202 
208,214, 240, 6,32, 254,210,0, $2, 254,219,0, 175, 11,2, 197,181,248, 89, $2,051,231 
164, 102,240.43, 173, 12,2,201, (57, 298,28, 32,250,297 0, 144,9, 152, 208, 74 166 
207,44, 98, 16, 7,200, 208,85, 164,207, 16, 61,202,292, 158, 164, TAZ, 208, 3,185,242 
0,0,6, 149,251,136, 208, 24f, 165,722, 145,251, 32,252, 109,G, 135,291, 132,257, 160 
64, 32,21, 254, 52, 106,757, $2,204,245, 16,253, 224,0,32,744,215,0,158, 180, 146 
Vt, 271,182. 240,12, 164. 104, 790,227,240, 5,0, 754 ASU, 16 247, 25h 292 DSA 
181,166, 85, $6, 751,40, 124, 527016 11, 5%, 56, 06,48 207.3200 Ad, OAM, 848? 
31, 209,6,64,9,04,7,09, 51, 2c) 8, A4, 4,08, 20%, 179, 2A Ae, TOU, OM, OF 
208, 140,44,0,0,0,17,34,68,51, 208, 140,05, 154,16, 34,68, 58,708,864, 4, 14, 54 
48,59 ,208,4,66,9.98,19, 120, 169,0,0,4, 35,129, 130,9-0,0,9,0,9.My, 12,149, 146 
134, 74,133, 151,448,419, 44, 34,40, 46.85,9,0,0, 5H, 58, 36,9,9,0, 24.1 My 7A, 55,98 
139,27. 161,157,156, 29,55, 147, 199,29,161,0,0,0,41,25, $74, 165,168.25, 35, 36 
63,27,93, 30,83, 25, 164,9,0,0, 20,91, 91,169,103, 14,50, 174 178, 168,175,48,0 
0,6, 134,0,0,0,21, 156, 17, 156, 165, 109,461,053, 157, 19,52, 19,164, 105, 49, 166, 216 
91,90, 19, 58,98, 140, 146, 044i, 20 8A, 104068, 2 97,148,000, 190, 0, 192, 118, 180 








40,190, 116,244,204, 74,114,242, 16d, 1 98,01,0,0, 170,147, 142,116,114, TIA, Dd 
6A, 104, 178,50, 079,0,0,9,54,0,0,1, 26,70, A, O11 a 8 2d 19 202 
72, GA, GH, 167, 20A0,4, 34, 18, 32,45,47, 90 84, 20,72 AAPA 9, 1, PAO, 290 
PAPO, 241,80, 291, 00%, 290, OOF, 292, 2398,0,7595, 00,9, 294,215, 0,295, 04,0 
09,293,255, 132,0, 7%, 45,4, 290, 70,0 


~492- Appendices: Supermon 


Se emt ee 


= Thee 


NULL 


ENQUI 
RING 


wennauvraun“o 


FORM 


CARRIAGE RETURN 


SHIFT 
SHIFT 
DATA 


DEVICE CONTROL #1 
DEVICE CONTROL #2 
GEVICE CONTROL #3 
DEVICE CONTROL #4 
NEGATIVE ACKNOWLEDGE 
SYNCHRONOUS IDLE 

ENO TRANSMISSION BLOCK 
CANCEL 

END MEDIUM 
SUBSTITUTE 

ESCAPE 

FILE SEPARATOR 

GROUP SEPARATOR 
RECORD SEPARATOR 


UNIT 


ASCII! characters, T 


START HEADING 
START TEXT 

END TEXT 

END TRANSMISSION 


ACKNOWLEDGE 


BACKSPACE 

HORIZONTAL TABULATION 
LINE FEED 

VERTICAL TABULATION 





‘CBM ~$93- Appendices: ASCH code 





ASCII CODE 





CHARACTER 


RY 
BELL 


+n TH ww Ee 


FEED 


. 


Out 
IN 
LINK ESCAPE 


“OeSBnNDOUEWN SK Oo: 
CINK K <Crenrnovossarrwrw so A Os ow - 


| Pr rmrNXKECCHYDOVOZEF AST TOMMOOUsS 





www AS 


SEPARATOR 


he American Standard Code on Information Interchange (ASCII) 


ts largely followed by CBM equipment. One major difference is its use of the high bit 
as a perity bit, making the number of 'l's In the complete byte even, CBM's version 
of 'ASCII' has no parity bit, 


a 
iia teetl be eens ine sainden Se neamendieie 


. 
pe al CF EN SY SS SE A EE RE EH eR mer parr ER! PP eu A 
z unis 





Appendices: Addenda 


gramming the PET /CBM ~$96- 


ADDENDUM 


» FAT- 40 ftwelve inch screen, 40-column CBM) is somewhat underrepresented in this book. tts 
SIC, sometimes called BASIC 4.41 to distinguish it from the eight inch screen 's BASIC 4.40, tS 
iitar ta other BASIC 4s except for the EQ0O AGM, which mainly affects keybcard and screen 
ilities. The jump tables on p.424 in Chapter 15 have some different destinations, for example, 
[HTAB and VTAB use SYS §7457. Also a FAT- 40 FOO ROM or EPROM in an eghtinch screen 
aiputer with BASIC 4 equips the machine with FAT-40 facilities such as repeat keys, but not of 
urse those associated with the CAT controier er bell. 
3 8096/5 an 8032 fitted with 32K exira RAM, Briefly, J2K is added to the top half of memory, from 
900 to £FEFF. Each of the Iwo Sets of 32K in high memory is orwided into two sels of 16K, SO 
itatany time two of the 16K blocks are in use. making four permutations. Sofor example a BASIC 
ygram might reside in love memcry, with BASIC itself occupying the high end of memory. The 
‘4a memory can be accessed by poking location SEFFO; bits 2 and 3 sefect the current pair of 
K blocks which are to be active, BASIC itself will be temporartiy fost, so SYS commands and 
ichine-code have to be used, and the technique /s not elementary. Machine-code is therefore 
ually used, as with VisiCalc, however, since BASIC can be solt-loaded (te. held in RAM, not 
M) any version of Commodore BASIC, including user-mocified versians, Can UE TUN, if the 
reen is confirgured to the correct column wigth by the CAT chip. Aleriaive BASIC's are 
‘ailable on disk, including some for 50 and 60Hz displays, and afso inching BASIC 5. The 
¥ect is similar, but more far-reaching, to that obta ned by refocating ROM routines into RAM as 
stined in Chapter 13. 
i1¢ ‘Super-PET’ of series 9000 has 64K extra RAM, in 16 blocks aif storedin $9000 to $OFFF and 
tectable by software. The machine has various hardware modifications and several languages, 
‘developed at Waterloo University in Canada. Atthe time of writing, translated versrons of BASIC, 
BOL. Foran, Pascal and APL have been written, The computer was partly intended for 
ynputer programming students. 
ymmodore have tried a number of experiments with cheaper computers, nolably the VIC-20 
ad VIC-40, which have 23 and 40 column screen outputs respectively, The evolution of these 
oducts has not been free of problems New features include the RS232 interface, the custom 
deo chips, high resolution graphics using RAM, and eight extra keys generauing CHAE (133) to 
HAS (140) The Commodore 64 uses 4 New Chip, the 6509, and is likely to be an improvement 
n its predecessors. 


‘otes on the text Some of the periodicals mentioned are no tonger published; and there 

an inevitable tendency for hardwara to be improved! or superseted. 

mpographical errors and orussions include. 

7: RESTORE is abbreviated by RE shilt-S 

14: S=O0: £0 before DIM keeps tte array porters correct 

58: DIM sets up the variable or variables following DIM so that DIM, A.B %,CS for example sels 
A, B%, and CS 11 that order in RAM. 

126: CHAE (18), not CHAS (8), produces 2 reversed program name 

137: The POKE location is 3, 4, of 16 depending on (he varsion of BASIC in use. 

(250: The lines are horizontal, not vedical. The chagram omits dots produced by the special 
character when values of 128 are inctifed 

265: "S" of "5" homes the cursor; the character 25 printed clears the screen. 

348: BASIC 4's keyboard interrupt doesnt work corrucily when the dacimui tag is sat, So SEH 
SEDI perform proces«ing! CLD! CLE may by neces siaty. 


Vth dvectaccess te Commodore disks, eiuly versions ot disk ROM will not votihe budter poratario 
ero, $0. 8 P muy give errors because ofthis, Note that BW stores tha butter potter in byfe 700 
iefore witing the block to disk, which will wreck the chaining of disk files itis ungaiectod BA 
ils up end of ite detechon based onthe sume parnter in byte 2ero. For tes. aa sons, Ue ane u} 
ire pteturrecd. 

OCKSMHH ip.t77), ranamed LOCKDISK, 1 4 progear by Jim Bittertetd 


ere = err nee ee me, i et 





Progromming the PET/CBM -497- Index 
INDEX 
BASIC: Anomalies 36° Break/ restart see 


8502 254, 307 ff, 310 FF. 982 FF 
6504 192 (In CBM disk drives} 
6520 343 fF C'PIA') 
6522 386 fF C'VIA') 
6845 270 ff (‘CRT contretter') 


4 


_A extended monitor assembly, 300 
ABS (BASIC) 38 ‘Approx. equality 444, 454 
Accuracy see e.g. 55, 6572, 121 £2}, 442 
ACT Ltd 199 
A-D Conversion anulog to digital. 264 
ADC (6502 opcode} add with carry 323 
Addressing Modes, 6502, 310, 320, 486, 489 
Alcock, D. 54, 460 
Algorithms 2}, 728 
Aflason, J. 60 
AND (BASIC) 16-bit operator, 39 

” AND (8502 opcode) 8-hit operator 324 
Animation 282 /surecen replacement 243 
APPEND (BASIC 4 Gdisk) 215 (see CONCAT 
APPEND joins BASIC programs, 41 
Apple 1, 5. 15, 52. 75, 92, 105, 129, 125, 142, 

144, 156, 273, 237, 236, 254, 265, 272, 289 
Arrays 33 fstorage 10 /pointers 14, 48, 
59, 153 {sce Matrices 

Arrow faust tape system, 236 
ASC (HASIC) opp. of CHR$, 43 
ASCit Commodore 266 /Standard $93 
ASL (6502 opcode) shift left, 324 
Assembler j6! 
Assignment Statement see LET 
Assn. of London Computer Clubs 2 
ATN (BASIC) arctangent, 44 
ATN {(LEEE Attention?, 375, 379 [2] 
AUTO yenerates linenumbers, e.g. 94 


6 Brenk flay set on BRK, 312 

.8 Extrumon brenkpoint setting, 300 

B-A (CEM Disk) block ullocate, 144 
BACKUP SRASIC 4 disk) 276 ¢ DUPLICATE 
7BAD DATA ERROR ace GET, INPUT 
7BAD OISK CRROR 230 

IBAD SUGSCRIPT ERROR 115 Mere? 
Baker, R. 1/76 

Barker, P. 253 


BASIC PASI) (Old HOW). HASIC 2 CUP BVS Cbafhe opeaie) branch HW set. 


yrade HOM'?, BASIC 4 Dink HASTCH, 
see Chapter 5, Chapter 7 Pehiffercneasss 
fh and wig. arrays, vf ert. The it}, 
ret dick, Atae ThE, Pie Liay, eg?! 

MUM, 276/ OREN. tas PEEK, Jae? seqaen 
editing. 275/ SHft Stap, 24 Pape stringga, 
ay, Pht, LEFTSE Tape, 244 


ns . 
Se rverearmgungy mee ree on a aman camtieme cnemarars ate eT Ce 


CONT, END, STOP Machine-code sce 
PEEK, POKE, SYS, USR Pointers 70 / 
altering, e.g. ?4, 98, 59,97, Too, 135, HIMEM 
and LOMEM 92 /free RAM 67 {2} 
RUN $2, 152{6], 355 see CHRGET 
Storage Keywords (& short forms) Chap~ 
ters 5 8 7 /Lines: deletion, see DEL; 
machine~code ta fetch and process, 6, 35% 
355; null byte, e.g. at start. 97 {ji 
Link pointers, 13-15, and e.g. 129, tst{t} 
scombining lines, LIST, search and re- 
piace ac, 14, 42, 84,751,369; Tokens and 
linked list, 5,6, 187 iit 
Subroutines use of, e.g. 23 
Syntax 11-12, 32, individual commands 
Chaos. 5 & 7, ambiguities c.g. 143 
Timing 75, 16, 52, 65 {4} 

Baum, A. 298 

BCC (6502 opcode) branch if C clear, 325 

BCD Binary coded decimal mode, ©€.F. 323 

BCS (6502 opcode) branch if carry set, 325. 

B-E (CRM disk) block execute. 14? 

Bennet, M. 60 . 

BEQ (6502 opeede) branch if vero set, 326 

Best, P. 2 

B-F (CBM disk) block free, 189 

Binary chop ssarch 30-37 

Bit 294 

BIT (6502 opcode) test and flag bits, 326 

BM! (6502 opcade) branch if N set. 327 

BNE (6562 opcode) branch if 7 clear, 327 

Boolean logic sec e.g. NOT, AND. OR in 
BASIC, AND, EOR, ORA in machine-corde ; 
applications, e.g. filed, 165 % 168 

B-P (CRM disk) buffer pointer, now U1, 789 

BPL (6502 opcode) tranch if N clear, 328 

Brandon, E. 6? 

Brannon, C, 6} 

BRK (6502 opcode) save data, jump 328 

Broomhall, H. 767, 226, 233 

Bubble Sort 3/, 133, 136 

Buffers: 1EEE character, 394 / {NPUT, 
392 and sce BASIC Storage / Keyboard, 
292 nnd sea Keyboard / Tape J?? and 
sev ‘Tape 

Busdiecker, R. 47 

Butler, 8, 749 

Butterfield, J. 2, 80, 93, 120, 176, 145, £92, 
219, 222, Ato, 298, 448 

BVCG f65U2 qpended vranch if V eloar, 29 

Pad 

A-W (CHM disk) buffer write, new U2, 187 

Byte 244 


HiByte magazine 159, 198, 289, 24, ae 


SBYTE aevusnbler directive Tt 


ee a ee ee RN 





igrumming the PET /CBM 


@ non-zero in BASIC, eg. IF 75; 

it set 1 = true in machine-code, eg. 
ND 324; bit set to 0 = true in IEEE 
as. eg. J75 

© (6502 opcode) transfer stack pointer 
> X, so SP can be found, 349 

‘nbull, T. 152 

& ($302 opcode) transfer X to A, 149 
5 (8502 opcode) transfer K to stack 
olnter, so SP can be changed, 350 

A (8502 opcode) transfer Y to A, 350 


“teen 


-504- index 


VARPTR finds variable (nat TI tc), 755 

VOU visuel display unit; see Screen 

Vectors, hardware of 6502 440 

VERIFY (BASIC) Loads and compares, 
but does not store, RAM image, 179, 156 

WERIFY ERROR 756 

VIA Versatile Interface Adaptor, 6522 
chip, 383-390 / Display contents, 343 / 
User Port, 387 / Diagram, 349 / 
Programming, 390 

VIC) ('Video Interface Chip'}, 03, 76, 
78, 243, 235, 254, 261, 265, £67, 272 

VisiCalc 263, 451%, 475 


Ww 


Unit number, BASIC 4 parameter, eg. 223 WAIT (BASIC) tests bits at location, 157 


Undo software uncrash, Extramon, 307 
,-UJ CBM disk jump table, 192 

ILIST BASIC utility, notes [51 

per case/Graphics see Screen Mades 
er Port position, 3 / Connected to ViA 
Port A, 399-390 / Top connectors, see 
CBM manual / PAG -PA7 and CB2 for 
sound, 288-293; see Disgnostic sense 
pin; tape luading and top connectors of 
user port, 297 

ers 477 ff 


1R (BASIC) inputs expression after USR 


Wedge 366 ff; DOS Support (='Universai 
Wedge’), 169, 217; Also 144 [2], 152 {5} 

Weinberg, G. 2, 199, 33%, 459 

Weizenbaum, J. 2 

Wilson, A. 45! 

Winchester disks [58 

.WORD assembler directive, 363 

Wardcraft 256, 476 

Wordpro 775, 475 

Wozniak, S. 298 


into Floating-point Accumulator 44, then X 


jumps to location $6, 753, example, $33; 
need not be JMP at $0, 153 [32} 
‘RCMO MLM extension vector, 294 


Internal overflow flag, 312, 329 
&L (BASIC) converts string, as far 46 


it Ig a valid representation of a umber, 


into numeral, 154 

ALIDATE BASIC < 4 disk command; sec 
COLLECT 

alidation examples, 32 ff 


_X MLM command, ‘Exit! to BASIC, 298 
X-register 308 - 309 
X2 Crash 262 


Y 
Yob, G. 2, 87, 721 


z 


2 Zero flag, set when result wae 6, 312 
Zaks, R. 264, 292 


ariables Rules of nanring, 7: longer names Zelier's Congruence for day sf week, 24 


with example table, 8; must begin with 
alphabetic, £79: Storage of variables, 


Tera page J/3, 392 ff; temporary save, 
then restore, 3/8; exaniple in TRACE 


BASIC pointers, 10; simple 8; sudscript- Zimmermann, M, 293, 494 
ed 9~+10; floating-point, inlogec, string, 2X8) 124, 473 


and function definitions, 9-10 end ug. 
442; watching vorinbles form, by con-* 
fining RAM te screen, Tf, 72 iv 
Machine-code, VARPTR uses LET: ex- 
amples fetch varlibie vatue, 4672 
PRINT USING inputs values, 727 
Assignment, varlibles freely redefin- 
able, #4; set up in RAM unless on 
right, except arraya, 4% 


ae a ee oh RR RT OA + NV In AN er I AE rem 


re soe . 
Ee ap ae ne ee eS REM ERS Gt ER nahn germ RARER mR rt SR i He RN TTT 
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